gloomberb 0.16.4 → 0.16.5

package/src/cli/commands/market.ts

@@ -10,7 +10,7 @@ import type {
   Quote,
   TickerFinancials,
 } from "../../types/financials";
-import { currencyMinorDigits, formatMarketPrice, formatMarketPriceWithCurrency, quoteFormatOptions } from "../../market-data/market/format";
+import { currencyPriceMinDigits, formatMarketPrice, formatMarketPriceWithCurrency, quoteFormatOptions } from "../../market-data/market/format";
 import {
   EXTENDED_SESSION_LABELS,
   getExtendedSessionDisplay,
@@ -21,7 +21,7 @@ import {
 } from "../../market-data/market/status";
 import { formatCompact, formatDistributionAmount, formatPercent, formatPercentRaw } from "../../utils/format";
 import { withCliServices, withMarketData } from "../context";
-import { isoDate, parsePositiveInt, rejectExtraArgs, requireOneArg, takeFlag, takeOption } from "./command-utils";
+import { isoDate, parsePositiveInt, requireOneArg, takeFlag, takeOption } from "./command-utils";
 import type { BuiltinCliCommandDef } from "../command-options";
 import { CLI_COMMAND_GROUPS, TABLE_SECTION_OPTION } from "../help";
 import {
@@ -30,7 +30,7 @@ import {
   formatFractionPercentCell,
   formatPriceRange,
 } from "../helpers";
-import { cliStyles, renderStats } from "../../utils/cli-output";
+import { cliStyles, colorBySign, renderSection, renderStats } from "../../utils/cli-output";
 import { formatPerShareNumber } from "../../utils/reported-money";
 import {
   analystTargetCurrency,
@@ -43,7 +43,9 @@ import {
 import { getPublishedUsEquityCalendarYears, getPublishedUsEquitySession } from "../../market-data/published-us-sessions";
 import { isQuoteStaleForCurrentSession } from "../../market-data/quotes/freshness";
 import { isOptionsUnavailableError, listedOptionsAlternative, optionsUnavailableTitle } from "../../market-data/options-alternatives";
-import { fundamentalsReportTables, renderFundamentalsReport } from "./ticker";
+import { cliFuturesContract, futuresContractMetrics, fundamentalsReportTables, renderFundamentalsReport } from "./ticker";
+import type { FuturesContractTermsPayload } from "../../api-client/futures-curve";
+import { futuresSettleText, isFuturesInstrument } from "../../market-data/futures-contract";
 import {
   chainHasExpiry,
   chainWithModelFigures,
@@ -69,6 +71,7 @@ import {
 import {
   historyFacts,
   historyFlagNote,
+  historyGapNote,
   historyAllRangeYears,
   historyIntervalsByRange,
   historyNotes,
@@ -77,10 +80,13 @@ import {
   historyUnit,
 } from "../history-rows";
 import { CRYPTO_BOARD_HINT, quoteNotes } from "./crypto-hints";
+import { bareFuturesCode } from "../../market-data/futures-board";
+import { newsEmptyMessage } from "./news-hints";
+import { newsFallbackText, newsSearchHeading, newsSearchText, newsSearchTextProblem, searchNewsStories } from "./news-search";
 import { formatUtcTime } from "../../utils/utc-time";
 import { isFiniteNumber } from "../../utils/guards";
 import { exportedFundamentals } from "../../utils/price-earnings";
-import { fundamentalsFreshness, quotesFreshness, rowsFreshness } from "../freshness";
+import { fundamentalsFreshness, fxPairFreshness, quotesFreshness, rowsFreshness } from "../freshness";
 import {
   barHistoryFreshness,
   barResolutionFromDates,
@@ -92,13 +98,19 @@ import {
 import {
   bareListingNote,
   EXCHANGE_OPTION,
+  futuresTryLine,
   isNoProviderError,
   listingHeading,
   listingIdentity,
   listingTitle,
   listingVenues,
+  listingChoiceNotes,
+  listingReadNotes,
+  loadBareVenues,
+  type ListingVenue,
   loadForListing,
   loadListingQuote,
+  noLongerTradingNote,
   notTradedMessage,
   quoteBareListing,
   requireCliListing,
@@ -106,18 +118,22 @@ import {
   type ListingDataRequest,
   type ListingIdentity,
 } from "../listing-arg";
-import { indexRootAlsoLine, indexRootFor, indexRootTryLine } from "../index-roots";
+import { indexRootAlsoLine, indexRootFor, indexRootTryLine, isYieldIndexSymbol } from "../index-roots";
+import { earningsCalendarFailure, earningsChoiceNote, earningsDateLabel, isListingAbroad, noListingCalendarNote } from "../earnings-calendar";
+import { formatBasisPoints, toBasisPoints } from "../../utils/basis-points";
 import { providerMissReason } from "../../sources/provider-errors";
 import { isNotATickerMessage } from "../not-a-ticker";
+import { splitSymbolArgs } from "../symbol-args";
 import { secRegistrantMismatchMessage, SecRegistrantMismatchError, areDifferentCompanies } from "../../sources/sec-registrant";
 import { isCryptoPairSymbol } from "../../utils/crypto-pair";
 import { isUsListingExchange } from "../../utils/exchanges";
-import { nonUsSecListingVenue } from "../../utils/sec";
+import { noSecReportsNotice, nonUsSecListingVenue } from "../../utils/sec";
 import type { MarketContext } from "../types";
 import { windowRows } from "../row-window";
 import { crossRate, describeFxRate, isUsableRate, parseFxRequest } from "../fx-pair";
 import {
   holderListFacts,
+  holderListPeriod,
   holderShareBasisMarker,
   holderShareBasisNote,
   holderValueBasis,
@@ -125,15 +141,27 @@ import {
   nonUsHolderCaveat,
   sharedReportDate,
 } from "../../plugins/builtin/holders/report-header";
-import { formatHolderOwnershipPercent, holderValueCurrency } from "../../plugins/builtin/holders/format";
+import { formatPercentHeld, holderStakeMarketCap, holderValueCurrency } from "../../plugins/builtin/holders/format";
+import {
+  holderReportColumns,
+  holderReportDates,
+  holderReportNotices,
+  holderReportRows,
+  holderReportUnits,
+  unvaluedHoldersNote,
+} from "../../plugins/builtin/holders/report-rows";
 import { fetchBeneficialOwners } from "../../plugins/builtin/holders/beneficial-client";
+import { classSharesToday } from "../../plugins/builtin/holders/client";
 import { filingFormMatches, SEC_FILING_FETCH_LIMIT } from "../../plugins/builtin/sec/forms";
+import { loadParsedInsiderFilings } from "../../plugins/builtin/insider/client";
+import { insiderEmptyNotice } from "../../plugins/builtin/insider/issuer";
 import {
   BENEFICIAL_REPORT_COLUMNS,
   beneficialCoverageNotices,
   beneficialListComplete,
   beneficialListFacts,
   beneficialListUnreadable,
+  beneficialReportLegend,
   beneficialRouteForm,
   buildBeneficialReportRows,
   HOLDER_FORMS,
@@ -144,7 +172,13 @@ import {
 const VALID_RANGES = new Set<TimeRange>(TIME_RANGES);
 const VALID_NEWS_FEEDS = new Set<NewsFeed>(["latest", "top", "breaking", "ticker", "sector", "topic"]);
 
-type QuoteCliRecord = Omit<QuoteBatchResult, "error"> & { error: string | null };
+type QuoteCliRecord = Omit<QuoteBatchResult, "error"> & {
+  error: string | null;
+  /** The listing the row is, named from its saved ticker when the quote names nothing. */
+  listing?: { name: string | null };
+  /** A futures row's contract, terms and latest confirmed settlement, as `ticker` reads them. */
+  futuresContract?: FuturesContractTermsPayload;
+};
 type FinancialsCliData = TickerFinancials & {
   symbol: string;
   exchange: string;
@@ -161,11 +195,9 @@ function parseNewsFeed(value: string | undefined): NewsQuery["feed"] | undefined
   return value && VALID_NEWS_FEEDS.has(value as NewsFeed) ? value as NewsQuery["feed"] : undefined;
 }
 
+/** The symbols of a command's arguments, one each however they were separated: spaces, commas or pasted lines. */
 function normalizeSymbols(args: string[]): string[] {
-  return args
-    .flatMap((arg) => arg.split(","))
-    .map((symbol) => symbol.trim().toUpperCase())
-    .filter(Boolean);
+  return splitSymbolArgs(args).map((symbol) => symbol.toUpperCase());
 }
 
 /** What JSON metadata says about the listing a command resolved. */
@@ -186,10 +218,15 @@ const QUOTE_LEAD_COLUMNS = [
       row.error && !value
         // A typo is not an outage: say what is wrong with the symbol itself.
         ? isNotATickerMessage(row.error) ? cliStyles.warning("not a ticker") : cliStyles.danger("unavailable")
-        : String(value ?? "")
+        : yieldLevelCell(value, row)
     ),
   },
-  { key: "changePercent", header: "Chg%", align: "right" as const, format: formatChangePercentCell },
+  {
+    key: "changePercent",
+    header: "Chg%",
+    align: "right" as const,
+    format: (value: unknown, row: QuoteRow) => row.yieldIndex ? yieldChangeCell(row) : formatChangePercentCell(value),
+  },
   // Text drops a column no row fills, so a table without an extended print stays as narrow as before.
   extendedColumn("PRE"),
   extendedColumn("POST"),
@@ -198,6 +235,17 @@ const QUOTE_LEAD_COLUMNS = [
 
 type QuoteRow = ReturnType<typeof quoteRows>[number];
 
+/** A Cboe yield index level is a yield: `5.24%`, not a price. */
+function yieldLevelCell(value: unknown, row: QuoteRow): string {
+  const text = String(value ?? "");
+  return row.yieldIndex && text ? `${text}%` : text;
+}
+
+/** A yield index moves in basis points: `+1.3bp`, from the real previous close, not a percent of a percent. */
+function yieldChangeCell(row: QuoteRow): string {
+  return row.changeBasisPoints == null ? "" : colorBySign(formatBasisPoints(row.changeBasisPoints / 100, 1), row.changeBasisPoints);
+}
+
 /** The pre-market or after-hours print and its move from the regular close, in its own column. */
 function extendedColumn(session: ExtendedSession) {
   return {
@@ -240,7 +288,7 @@ function quoteColumns() {
 function compareColumns() {
   return [
     ...QUOTE_LEAD_COLUMNS,
-    { key: "previousClose", header: "Prev Close", align: "right" as const },
+    { key: "previousClose", header: "Prev Close", align: "right" as const, format: yieldLevelCell },
     // A narrow terminal drops these before it cuts the names short.
     { key: "dayRange", header: "Day Range", align: "right" as const, optional: true, dropPriority: 1 },
     { key: "volume", header: "Volume", align: "right" as const, format: formatCountCell, optional: true, dropPriority: 2 },
@@ -267,13 +315,14 @@ function quoteRows(results: QuoteCliRecord[], now = Date.now()) {
     // pre-market or after-hours print is its own column, measured from that session's close.
     const display = getRegularSessionDisplay(quote);
     const extended = getExtendedSessionDisplay(quote);
+    const yieldIndex = isYieldIndexSymbol(result.target.symbol);
     // An index level is in points, not in the currency its members trade in.
     const indexPoints = quote?.instrumentType?.trim().toUpperCase() === "INDEX";
     // Pad to two decimals so a column lines up, but never past the currency's minor unit (JPY has none).
     // Points have no minor unit, so a yen-listed index still pads to two.
     const options = {
       ...quoteFormatOptions(quote),
-      minimumFractionDigits: indexPoints ? 2 : Math.min(2, currencyMinorDigits(quote?.currency)),
+      minimumFractionDigits: indexPoints ? 2 : currencyPriceMinDigits(quote?.currency),
     };
     const price = (value: number | undefined) => (
       quote && value != null
@@ -282,13 +331,16 @@ function quoteRows(results: QuoteCliRecord[], now = Date.now()) {
     );
     return {
       symbol: result.target.symbol,
-      name: quote?.name ?? "",
+      name: quote?.name || result.listing?.name || "",
       price: price(display?.price),
       rawPrice: display?.price ?? null,
       priceBasis: quote?.priceBasis ?? null,
       instrumentType: quote?.instrumentType ?? null,
       change: display?.change ?? null,
       changePercent: roundedPercent(display?.changePercent),
+      // A Cboe yield index is read as a yield in percent and moves in basis points.
+      yieldIndex,
+      changeBasisPoints: yieldIndex && display?.change != null ? toBasisPoints(display.change, 1) : null,
       extendedSession: extended?.session ?? null,
       extendedPrice: price(extended?.price),
       rawExtendedPrice: extended?.price ?? null,
@@ -349,22 +401,6 @@ function filingRows(filings: SecFilingItem[]) {
   }));
 }
 
-function holderRows(data: HolderData, ownerTypes?: Set<string>) {
-  const holders = ownerTypes
-    ? data.holders.filter((holder) => ownerTypes.has(holder.ownerType))
-    : data.holders;
-  return holders.map((holder) => ({
-    type: holder.ownerType,
-    name: holder.name,
-    reportDate: holder.reportDate ?? "",
-    shares: holder.shares ?? null,
-    value: holder.value ?? null,
-    percentHeld: holder.percentHeld ?? null,
-    changeShares: holder.changeShares ?? null,
-    shareBasis: holder.shareBasis ?? null,
-  }));
-}
-
 function analystSummary(data: AnalystResearchData): string {
   const target = data.priceTarget;
   const currency = analystTargetCurrency(data);
@@ -459,6 +495,8 @@ function earningsRows(events: EarningsEvent[]) {
     symbol: event.symbol,
     name: event.name,
     date: isoDate(event.earningsDate).slice(0, 10),
+    // Whether the company announced the date or it is projected from past reports.
+    status: earningsDateLabel(event),
     timing: event.timing,
     epsEstimate: event.epsEstimate,
     epsActual: event.epsActual,
@@ -467,6 +505,9 @@ function earningsRows(events: EarningsEvent[]) {
   }));
 }
 
+/** Symbols at most whose venues a command looks up to name the company each bare one went to. */
+const MAX_CHOICE_LOOKUPS = 10;
+
 async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1], commandName: "quote" | "compare") {
   const args = [...rawArgs];
   const exchange = takeOption(args, "--exchange") ?? "";
@@ -479,38 +520,87 @@ async function runQuote(rawArgs: string[], ctx: Parameters<CliCommandDef["execut
       symbol, exchange, market, ctx, { ownExchangeWins: symbols.length > 1 },
     )));
     const targets: QuoteSubscriptionTarget[] = listings.map((listing) => ({ symbol: listing.request.symbol, exchange: listing.request.exchange }));
+    // A bare symbol's venues load beside its quote, to name the company it was read as when several list it.
+    // Each costs a search, so a long list (a portfolio check, not a lookup) names none.
+    const venues = new Map(listings.length > MAX_CHOICE_LOOKUPS ? []
+      : listings.map((listing) => [listing, loadBareVenues(listing, market)] as const));
     const results = await market.dataProvider.getQuotesBatch(targets, { forceRefresh: ctx.cliOptions.refresh });
     const listingOf = (result: QuoteBatchResult, index: number) => listings[targets.indexOf(result.target)] ?? listings[index]!;
     const request = { command: commandName, noun: "quote" };
-    const answers = await Promise.all(results.map((result, index) => answerQuote(result, listingOf(result, index), market, request, ctx.cliOptions.refresh)));
+    const answers = await Promise.all(results.map((result, index) => {
+      const listing = listingOf(result, index);
+      return answerQuote(result, listing, market, request, ctx.cliOptions.refresh, venues.get(listing) ?? null);
+    }));
     const failed = answers[0]?.failure;
     if (listings.length === 1 && failed) ctx.fail(failed.message, failed.details);
+    // A futures quote adds its dated settlement and contract terms, as `ticker` prints them; `compare` stays a table.
+    const contracts = await Promise.all(answers.map(({ result }) => commandName === "quote" && result.quote
+      ? cliFuturesContract(result.quote.symbol || result.target.symbol, result.quote.instrumentType)
+      : null));
     // Each row names its listing by key (SAN:EPA) and company, so the table needs no line above it.
-    const data = answers.map(({ result, listing, failure }) => ({
+    const data = answers.map(({ result, listing, failure }, index) => ({
       target: result.target,
       listing: listingMetadata(listingIdentity(listing, result.quote)),
       // The figures the table shows, beside the quote as the source sent it.
       ...getQuoteSessionFields(result.quote),
       quote: result.quote,
+      ...contracts[index] ? { futuresContract: contracts[index] } : {},
       error: failure?.oneLine ?? errorMessage(result.error),
+      ...yieldIndexFields(result),
     }));
+    const now = Date.now();
     const notes = [
       // Which listing a bare symbol was read as, and the index a bare root is not, are in no row.
       ...answers.flatMap((answer) => answer.notes),
+      // A row that stopped trading long ago reads as a quote that is merely stale.
+      ...data.flatMap((row) => row.quote
+        ? noLongerTradingNote(`${row.target.symbol}${row.listing.name ? ` (${row.listing.name})` : ""}`, row.quote, now) ?? []
+        : []),
       // Text mode shows only "unavailable" in the cell; the JSON rows already carry each reason.
       ...ctx.cliOptions.format === "text" ? quoteNotes(data, { exchange }) : [],
     ];
+    const columns = commandName === "compare" ? compareColumns() : quoteColumns();
+    // Only yield indices: their change is in bp, so the text header drops the percent sign (CSV keeps the percent it holds).
+    const yieldsOnly = data.length > 0 && data.every((row) => isYieldIndexSymbol(row.target.symbol));
     ctx.printResult({
       data,
       warnings: notes.length > 0 ? notes : undefined,
       freshness: quotesFreshness(data.map((row) => row.quote)),
     }, {
       rows: quoteRows,
-      columns: commandName === "compare" ? compareColumns() : quoteColumns(),
+      details: quoteFuturesContractText,
+      columns,
+      ...(yieldsOnly ? { textColumns: columns.map((column) => column.key === "changePercent" ? { ...column, header: "Chg" } : column) } : {}),
     });
   });
 }
 
+/**
+ * Under the table, each futures row's Settle line and Contract block, worded
+ * as `ticker` words them. Several symbols name theirs in the block's title.
+ */
+function quoteFuturesContractText(data: QuoteCliRecord[]): string {
+  return data.flatMap((row) => {
+    const terms = row.futuresContract;
+    if (!terms || !row.quote) return [];
+    const settle: [string, string] = ["Settle", futuresSettleText(terms, row.quote)];
+    const contract = futuresContractMetrics(terms, row.quote.symbol || row.target.symbol);
+    if (data.length > 1) return [`${renderSection(`${row.target.symbol} Contract`)}\n${renderStats([settle, ...contract])}`];
+    return [[renderStats([settle]), ...contract.length ? ["", renderSection("Contract"), renderStats(contract)] : []].join("\n")];
+  }).join("\n\n");
+}
+
+/**
+ * What a Cboe yield index adds to its JSON row: the level is a yield in percent
+ * and its change since the previous close is in basis points (the quote's own
+ * `change` is the same move in percentage points).
+ */
+function yieldIndexFields(result: QuoteBatchResult): { unit?: "percent"; changeBasisPoints?: number } {
+  if (!isYieldIndexSymbol(result.target.symbol)) return {};
+  const change = getRegularSessionDisplay(result.quote)?.change;
+  return { unit: "percent", ...(change == null ? {} : { changeBasisPoints: toBasisPoints(change, 1) }) };
+}
+
 interface QuoteAnswer {
   result: QuoteBatchResult;
   /** The listing the row is: the one asked for, or the venue a bare symbol was quoted on. */
@@ -524,8 +614,10 @@ interface QuoteAnswer {
  * One symbol's row of `quote` and `compare`. A listing on an exchange its symbol
  * is not listed on says so. A bare symbol the data service read on its home
  * listing abroad names that venue (SXR8 -> XETRA). One no source quotes is
- * quoted on its listings (`quoteBareListing`), else names them; a bare index
- * root (VIX) also names its index (^VIX). Venues are only looked up for a
+ * quoted on its listings (`quoteBareListing`), else names them, or asks for an
+ * exchange when several companies list it (2222); a bare index root (VIX) also
+ * names its index (^VIX), and a futures board code a security keeps (GC) its
+ * future (GC=F). Venues are only looked up for a
  * symbol with no quote, so a request that succeeds costs no search.
  */
 async function answerQuote(
@@ -534,12 +626,18 @@ async function answerQuote(
   market: MarketContext,
   request: ListingDataRequest,
   refresh: boolean,
+  venues: Promise<ListingVenue[]> | null,
 ): Promise<QuoteAnswer> {
   const root = listing.exchange ? null : indexRootFor(listing.symbol);
   // A bare root that quoted something else, such as MOVE (Corvex), points at the index too.
   const also = (quote: Quote) => root && quote.instrumentType?.trim().toUpperCase() !== "INDEX"
     ? [indexRootAlsoLine(root, request.command)] : [];
-  if (result.quote) return { result, listing, notes: [bareListingNote(listing, result.quote) ?? [], also(result.quote)].flat() };
+  if (result.quote) {
+    // "CAR = Avis Budget Group, NASDAQ (also XETRA, ASX)" names the venue too, so it replaces "SXR8 -> XETRA".
+    const choice = venues ? await listingChoiceNotes(listing, market, result.quote, venues) : listingReadNotes(listing);
+    const venue = choice.length > 0 ? null : bareListingNote(listing, result.quote);
+    return { result, listing, notes: [...choice, venue ?? [], also(result.quote)].flat() };
+  }
   const notTraded = await notTradedMessage(listing, market);
   if (notTraded) return { result, listing, failure: { message: notTraded, oneLine: notTraded }, notes: [] };
   if (!isNoProviderError(result.error)) return { result, listing, notes: [] };
@@ -551,14 +649,18 @@ async function answerQuote(
       notes: [other.note, ...also(other.quote)],
     };
   }
-  const indexLine = root ? indexRootTryLine(root, request.command) : null;
-  if (!other && !indexLine) return { result, listing, notes: [] };
+  // Other listings already name a futures board code's future (GC=F); with none, it is named here.
+  const tryLines = [
+    root ? indexRootTryLine(root, request.command) : null,
+    other || listing.exchange ? null : futuresTryLine(listing.symbol, request),
+  ].filter((line): line is string => !!line);
+  if (!other && tryLines.length === 0) return { result, listing, notes: [] };
   const message = other?.message ?? `${listing.symbol} has no ${request.noun}.`;
-  const details = [other?.details, indexLine].filter(Boolean).join("\n");
+  const details = [other?.details, ...tryLines].filter(Boolean).join("\n");
   const oneLine = [
     message,
-    other ? `Other listings: ${other.others.join(", ")}.` : "",
-    indexLine ?? "",
+    other ? `${other.heading}: ${other.listings.join(", ")}.` : "",
+    ...tryLines,
   ].filter(Boolean).join(" ");
   return { result, listing, failure: { message, details, oneLine }, notes: [] };
 }
@@ -581,6 +683,7 @@ async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
   const raw = requireOneArg(args, HISTORY_USAGE, "symbol", ctx);
   await withMarketData(ctx, async (market) => {
     const listing = await requireCliListing(raw, requestedExchange, market, ctx);
+    const venues = loadBareVenues(listing, market);
     const { symbol, exchange } = listing.request;
     const context = { cacheMode: ctx.cliOptions.refresh ? "refresh" as const : "default" as const };
     const load = () => market.dataProvider.getPriceHistoryWithMetadata
@@ -596,7 +699,7 @@ async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
     const identity = listingIdentity(listing, quote);
     // Without a quote currency, the listing metadata research reads (as `ticker` does) may still state it.
     const listed = quote?.currency ? quote : await market.dataProvider.getQuoteMetadata?.(symbol, exchange).catch(() => null);
-    const unit = historyUnit(listing.symbol, listed ?? quote);
+    const unit = historyUnit(listing.key, listed ?? quote);
     const data = historyRows(points, resolution, unit.currency);
     const interval = data[0]?.interval ?? null;
     const decimals = historyPriceDecimals(data, listing.saved?.metadata.assetCategory);
@@ -608,8 +711,16 @@ async function runHistory(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
       ...barHistoryFreshness(intraday ? null : barResolutionFromDates(data.map((row) => row.date))),
       observedKey: "date",
       oldest: null,
+      // Bars stop arriving on the listing's own trading days, not New York's.
+      cadenceExchange: quote?.listingExchangeName || exchange || undefined,
+    });
+    const gaps = historyGapNote(data, {
+      listing: listing.key, exchange: quote?.listingExchangeName || exchange || undefined, instrumentType: quote?.instrumentType,
     });
-    const notes = [...historyNotes(range, interval, data[0]?.date), historyFlagNote(data) ?? []].flat();
+    const notes = [
+      ...await listingChoiceNotes(listing, market, quote, venues),
+      ...historyNotes(range, interval, data[0]?.date), gaps ?? [], historyFlagNote(data) ?? [],
+    ].flat();
     const priceColumns: CliResultColumn[] = [
       intraday
         ? { key: "date", header: "Time", format: (value) => typeof value === "string" ? formatUtcTime(value) : "" }
@@ -687,10 +798,12 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
   };
   await withMarketData(ctx, async (market) => {
     const listing = await requireCliListing(raw, exchangeOption, market, ctx);
+    const venues = loadBareVenues(listing, market);
     const financials = await loadForListing(listing, market, ctx, () => market.dataProvider.getTickerFinancials(
       listing.request.symbol, listing.request.exchange, { cacheMode: ctx.cliOptions.refresh ? "refresh" : "default" },
     ), undefined, { command: commandName, noun: commandName === "valuation" ? "valuation data" : commandName });
     const identity = listingIdentity(listing, financials.quote);
+    const choice = await listingChoiceNotes(listing, market, financials.quote, venues);
     const data: FinancialsCliData = {
       symbol: listing.key,
       exchange: identity.exchange,
@@ -703,6 +816,7 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
         // JSON reads a multiple over a loss as null with its reason, never as a number.
         data: { ...data, fundamentals: exportedFundamentals(data.fundamentals) },
         freshness,
+        ...(choice.length > 0 ? { warnings: choice } : {}),
       }, {
         text: () => renderFundamentalsReport(data, view),
         ...(tabular ? { tables: selectTables(fundamentalsReportTables(data, view, freshness)) } : {}),
@@ -731,6 +845,7 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
         profile: financials.profile,
       },
       freshness,
+      ...(choice.length > 0 ? { warnings: choice } : {}),
     }, {
       heading: listingHeading(identity),
       rows: () => rows,
@@ -740,16 +855,55 @@ async function runFinancials(rawArgs: string[], ctx: Parameters<CliCommandDef["e
   });
 }
 
+const NEWS_COLUMNS = [
+  // UTC with the zone named, as every CLI time prints, rather than the host zone unlabeled.
+  {
+    key: "publishedAt",
+    header: "Published",
+    format: (value: unknown) => typeof value === "string" ? formatUtcTime(value) : "",
+  },
+  { key: "source", header: "Source", maxWidth: 20 },
+  { key: "title", header: "Title" },
+  { key: "tickers", header: "Tickers", maxWidth: 16 },
+  { key: "url", header: "URL", optional: true },
+];
+
+/** Stories matching text, printed as a symbol's news is, under a line saying what they match. */
+async function printNewsSearch(
+  text: string,
+  articles: NewsArticle[],
+  { reason, empty }: { reason?: string; empty?: string },
+  ctx: Parameters<CliCommandDef["execute"]>[1],
+) {
+  ctx.printResult({
+    data: articles,
+    metadata: { ticker: null, search: text, feed: null },
+    freshness: rowsFreshness(newsRows(articles), cloudNewsFreshness(await cloudRealtimeAccess())),
+  }, {
+    heading: newsSearchHeading(text, reason),
+    rows: newsRows,
+    columns: NEWS_COLUMNS,
+    empty: empty ?? `No stories match "${text}".`,
+  });
+}
+
 async function runNews(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]>[1]) {
   const args = [...rawArgs];
   const feed = parseNewsFeed(takeOption(args, "--feed"));
   const exchangeOption = takeOption(args, "--exchange");
+  // Stories come newest first, so the newest n are the first n either way.
+  const limit = ctx.cliOptions.tail ?? ctx.cliOptions.limit ?? 20;
+  const text = newsSearchText(args);
+  if (text != null) {
+    if (exchangeOption || feed) ctx.fail(`${exchangeOption ? "--exchange" : "--feed"} goes with a symbol, not with text to search stories for.`, "Usage: gloomberb news <query>");
+    const problem = newsSearchTextProblem(text);
+    if (problem) ctx.fail(problem);
+    await printNewsSearch(text, await searchNewsStories(text, limit), {}, ctx);
+    return;
+  }
   if (exchangeOption && !args[0]) ctx.fail("--exchange needs a symbol: gloomberb news <symbol> --exchange <code>");
-  rejectExtraArgs(args, 1, { usage: "news [symbol] [--feed <feed>]", takes: "one symbol at most", advice: "Run it once per symbol." }, ctx);
   await withMarketData(ctx, async (market) => {
     const listing = args[0] ? await requireCliListing(args[0], exchangeOption, market, ctx) : null;
-    // Stories come newest first, so the newest n are the first n either way.
-    const limit = ctx.cliOptions.tail ?? ctx.cliOptions.limit ?? 20;
     const loadNews = () => market.dataProvider.getNews({
       feed: feed ?? (listing ? "ticker" : "latest"),
       // Still set for news plugins that read the deprecated scope.
@@ -763,25 +917,33 @@ async function runNews(rawArgs: string[], ctx: Parameters<CliCommandDef["execute
       listing ? loadListingQuote(market.dataProvider, listing) : null,
     ]);
     const identity = listing ? listingIdentity(listing, quote) : null;
+    const resolved = quote !== null || identity?.name != null;
+    // A bare word no listing answers to is text, and so is a futures board code (TTF), which resolves
+    // to its future: news is filed under company tickers, so the stories that mention the word are the news.
+    const word = listing && !listing.exchange && !feed && articles.length === 0 ? newsFallbackText(args[0]!) : null;
+    const futuresCode = !!word && !!bareFuturesCode(word) && isFuturesInstrument(listing!.symbol, quote?.instrumentType);
+    const reason = !resolved ? "no ticker by that name" : futuresCode ? "a futures code, not a ticker" : null;
+    const emptyMessage = (searched: boolean) => listing && identity
+      ? newsEmptyMessage(searched && word ? word : listing.symbol, listingTitle(identity), quote, resolved, searched)
+      : undefined;
+    if (word && reason) {
+      // The lookup that found no ticker already answered; a search that fails leaves that answer.
+      const found = await searchNewsStories(word, limit).catch(() => []);
+      await printNewsSearch(word, found, { reason, empty: emptyMessage(true) }, ctx);
+      return;
+    }
+    const empty = emptyMessage(false);
+    const read = listing ? listingReadNotes(listing) : [];
     ctx.printResult({
       data: articles,
+      ...(read.length > 0 ? { warnings: read } : {}),
       metadata: { ticker: listing?.key ?? null, ...(identity ? listingMetadata(identity) : {}), feed: feed ?? null },
       freshness: rowsFreshness(newsRows(articles), cloudNewsFreshness(await cloudRealtimeAccess())),
     }, {
       ...(identity ? { heading: listingHeading(identity) } : {}),
       rows: newsRows,
-      columns: [
-        // UTC with the zone named, as every CLI time prints, rather than the host zone unlabeled.
-        {
-          key: "publishedAt",
-          header: "Published",
-          format: (value) => typeof value === "string" ? formatUtcTime(value) : "",
-        },
-        { key: "source", header: "Source", maxWidth: 20 },
-        { key: "title", header: "Title" },
-        { key: "tickers", header: "Tickers", maxWidth: 16 },
-        { key: "url", header: "URL", optional: true },
-      ],
+      columns: NEWS_COLUMNS,
+      ...(empty ? { empty } : {}),
     });
   });
 }
@@ -809,6 +971,7 @@ async function runFilings(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
   const raw = requireOneArg(args, "filings <symbol> [--count <n>] [--form <form>]", "symbol", ctx);
   await withMarketData(ctx, async (market) => {
     const listing = await requireCliListing(raw, exchangeOption, market, ctx);
+    const venues = loadBareVenues(listing, market);
     const { symbol, exchange } = listing.request;
     // A listing outside the US sends its company to the lookup, which needs its quote first.
     const quotePromise = loadListingQuote(market.dataProvider, listing);
@@ -825,15 +988,20 @@ async function runFilings(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
         quotePromise,
       ]);
       const resolved = identity ?? listingIdentity(listing, quote);
+      const choice = await listingChoiceNotes(listing, market, quote, venues);
       ctx.printResult({
         data: filings,
         metadata: { ...listingMetadata(resolved), ...(form ? { form } : {}) },
         freshness: rowsFreshness(filingRows(filings), { ...SEC_FILINGS, observedKey: "filingDate" }),
+        ...(choice.length > 0 ? { warnings: choice } : {}),
       }, {
         heading: listingHeading(resolved),
         rows: filingRows,
         columns: FILING_COLUMNS,
-        empty: form ? `No ${form} filings found for ${listingTitle(resolved)}.` : `No SEC filings found for ${listingTitle(resolved)}.`,
+        // A listing abroad is looked up by its company: none found means the company files nothing with the SEC.
+        empty: form ? `No ${form} filings found for ${listingTitle(resolved)}.`
+          : identity ? noSecReportsNotice(resolved)
+          : `No SEC filings found for ${listingTitle(resolved)}.`,
       });
     } catch (error) {
       if (!(error instanceof SecRegistrantMismatchError)) throw error;
@@ -851,17 +1019,50 @@ async function runFilings(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
   });
 }
 
+type Form4Insiders = "available" | "none" | "foreign-private-issuer" | "no-sec-reports";
+
+/**
+ * Whether the company has Form 4 filings of its own, read as `fn INS` reads
+ * them; null when they could not be read. A listing abroad the SEC lists
+ * nothing for files no SEC reports at all.
+ */
+async function loadForm4Insiders(market: MarketContext, listing: CliListing): Promise<Form4Insiders | null> {
+  try {
+    const { parsed, foreignPrivateIssuer, noFilings } = await loadParsedInsiderFilings(market.dataProvider, listing.request.symbol, {
+      limit: 1,
+      exchange: listing.request.exchange,
+    });
+    if (parsed.length > 0) return "available";
+    if (noFilings && nonUsSecListingVenue(listing.request.symbol, listing.request.exchange)) return "no-sec-reports";
+    return foreignPrivateIssuer ? "foreign-private-issuer" : "none";
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Holder lists name institutions and funds; individual insiders rarely appear.
- * The insider share of the company is reported either way, so say it.
+ * The insider share of the company is reported either way, so say it. The
+ * Form 4 trades are pointed to only when the company has some; otherwise the
+ * line says why there are none, in the words `fn INS` uses.
  */
-function insiderSummary(data: HolderData, ownerTypes: Set<string>): string {
+function insiderSummary(
+  data: HolderData,
+  ownerTypes: Set<string>,
+  listing: Pick<CliListing, "key">,
+  identity: ListingIdentity,
+  form4: Form4Insiders | null,
+): string {
   const held = data.summary?.insidersPercentHeld;
   const share = held == null || !Number.isFinite(held)
     ? ""
     : `Insiders hold ${formatFractionPercentCell(held)} of shares outstanding.`;
   const listed = data.holders.some((holder) => ownerTypes.has(holder.ownerType));
-  const transactions = listed ? "" : `Form 4 transactions: gloomberb fn INS ${data.symbol}`;
+  // The listing as the command read it (CAR:ASX), not the source's spelling of it (CAR.AX), which fn does not take.
+  const transactions = form4 === "available"
+    ? listed ? "" : `Form 4 transactions: gloomberb fn INS ${listing.key}`
+    : form4 === "no-sec-reports" ? noSecReportsNotice(identity)
+    : form4 ? insiderEmptyNotice(form4 === "foreign-private-issuer") : "";
   return [share, transactions].filter(Boolean).join("\n");
 }
 
@@ -878,14 +1079,18 @@ async function printBeneficialOwners(
   const quotePromise = loadListingQuote(market.dataProvider, listing);
   const abroad = nonUsSecListingVenue(symbol, exchange) ? listingIdentity(listing, await quotePromise) : null;
   const request = { form: beneficialRouteForm(form), history, listing: { exchange, name: abroad?.name ?? undefined } };
-  const [payload, holders, quote] = await Promise.all([
+  const [payload, holders, quote, financials] = await Promise.all([
     loadForListing(listing, market, ctx, () => fetchBeneficialOwners(symbol, request)),
     market.dataProvider.getHolders?.(symbol, exchange).catch(() => null) ?? null,
     quotePromise,
+    // Today's share count, which the filed percents are set against.
+    market.dataProvider.getTickerFinancials(symbol, exchange).catch(() => null),
   ]);
   const identity = listingIdentity(listing, quote);
-  const rows = buildBeneficialReportRows(payload, { history, holders });
+  const sharesOutstanding = classSharesToday(financials);
+  const rows = buildBeneficialReportRows(payload, { history, holders, sharesOutstanding });
   const notices = beneficialCoverageNotices(payload.coverage);
+  const legend = beneficialReportLegend(rows, sharesOutstanding);
   ctx.printResult({
     data: rows,
     ...(notices.length ? { warnings: notices } : {}),
@@ -898,12 +1103,16 @@ async function printBeneficialOwners(
       asOf: payload.asOf,
       coverage: payload.coverage,
       complete: beneficialListComplete(payload),
+      sharesOutstanding,
     },
   }, {
     heading: `${listingHeading(identity)}${cliStyles.muted(beneficialListFacts(payload, form, rows.length, history).map((fact) => `  ·  ${fact}`).join(""))}`,
-    textColumns: BENEFICIAL_REPORT_COLUMNS,
+    // Text draws each column as the HDS report does; CSV and JSON keep the raw values.
+    textColumns: BENEFICIAL_REPORT_COLUMNS.map((column) => ({ ...column, format: column.textFormat ?? column.format })),
+    ...(legend ? { footnote: legend } : {}),
     columns: [
-      ...BENEFICIAL_REPORT_COLUMNS,
+      ...BENEFICIAL_REPORT_COLUMNS.map(({ key, header, align }) => ({ key, header, ...(align ? { align } : {}) })),
+      { key: "otherPersons", header: "Other persons" },
       { key: "status", header: "Status" },
       { key: "filerCik", header: "Filer CIK" },
       { key: "accessionNumber", header: "Accession" },
@@ -911,6 +1120,8 @@ async function printBeneficialOwners(
     ],
     empty: beneficialListUnreadable(payload)
       ? `13D/13G filings for ${listingTitle(identity)} are listed but could not be read.`
+      // The SEC knows no company for a listing abroad that files there under no name of its own.
+      : abroad && !payload.cik ? noSecReportsNotice(identity)
       : `No 13D/13G filings in the last 4 years for ${listingTitle(identity)}.`,
   });
 }
@@ -932,7 +1143,9 @@ async function runHolders(
   await withMarketData(ctx, async (market) => {
     const listing = await requireCliListing(raw, exchangeOption, market, ctx);
     if (form !== "13f") return printBeneficialOwners(listing, market, form, history, ctx);
-    const [data, quote] = await Promise.all([
+    const insiderCommand = commandName === "insider" && ownerTypes != null;
+    const venues = loadBareVenues(listing, market);
+    const [data, quote, form4] = await Promise.all([
       loadForListing(
         listing, market, ctx,
         () => market.dataProvider.getHolders(listing.request.symbol, listing.request.exchange),
@@ -940,43 +1153,70 @@ async function runHolders(
         { command: commandName, noun: "holder data" },
       ),
       loadListingQuote(market.dataProvider, listing),
+      insiderCommand ? loadForm4Insiders(market, listing) : null,
     ]);
     const identity = listingIdentity(listing, quote);
-    const rows = holderRows(data, ownerTypes);
-    const shown = windowRows(rows, ctx.cliOptions).rows.length;
+    const choice = await listingChoiceNotes(listing, market, quote, venues);
+    // A London line's values can be dollars from the 13F filings; the listing's currency is not their unit.
+    const valueCurrency = holderValueCurrency(data, "USD")!;
+    // The rows, their units and their order are HDS's, so `holders --csv` and `fn HDS --csv` agree.
+    const rows = holderReportRows(data, {
+      marketCap: holderStakeMarketCap(quote?.marketCap, quote?.currency, valueCurrency),
+      ownerTypes,
+    });
+    const shownRows = windowRows(rows, ctx.cliOptions).rows;
+    const shown = shownRows.length;
     const institutional = !ownerTypes?.has("insider");
     const total = institutional ? data.summary?.institutionsCount ?? null : null;
     const reportDate = sharedReportDate(rows);
-    // A London line's values can be dollars from the 13F filings; the listing's currency is not their unit.
-    const valueCurrency = holderValueCurrency(data);
     const valueBasis = rows.length > 0 ? holderValueBasis(reportDate, data.valueBasis, valueCurrency) : null;
     const positionsBasis = rows.length > 0 ? nonUsHolderCaveat(identity.exchange || data.exchange, data.currency) : null;
     const shareBasisNote = holderShareBasisNote(data, rows);
     const markedRows = rows.some((row) => holderShareBasisMarker(row));
     // The heading names the listing; its unit, date and how much of the list follows on the same line.
+    // One "as of" only when every row shown is of that date; each row carries its own.
     const facts = holderListFacts({
-      currency: valueCurrency, listingCurrency: data.currency, asOf: data.asOf, shown, reported: rows.length, total,
+      currency: valueCurrency,
+      listingCurrency: data.currency,
+      period: holderListPeriod(shownRows, data.asOf),
+      shown,
+      reported: rows.length,
+      total,
+      ranked: !positionsBasis,
     });
+    const unvaluedNote = unvaluedHoldersNote(shownRows);
+    const columns = holderReportColumns(shownRows, valueCurrency);
+    // Dated as HDS dates it: by the list's as-of.
+    const freshness = rowsFreshness(shownRows, { ...SEC_FILINGS, basis: "13F filings" }, { asOf: data.asOf ?? null });
+    // Named as fn HDS takes it, so the closing notes point to the same listing.
+    const requested = exchangeOption && !raw.includes(":") ? `${raw}:${exchangeOption.toUpperCase()}` : raw;
+    const { notices } = holderReportNotices({ data, requested, shown: shownRows, reported: rows.length, total });
     ctx.printResult({
-      data,
+      data: rows,
+      ...(freshness ? { freshness } : {}),
       metadata: {
         ...listingMetadata(identity),
-        summary: data.summary,
+        summary: data.summary ?? null,
         currency: data.currency ?? null,
-        valueCurrency: valueCurrency ?? null,
+        valueCurrency,
+        units: holderReportUnits(valueCurrency),
         asOf: data.asOf ?? null,
+        // Each holder's latest period; several when the list mixes quarters.
+        reportDates: holderReportDates(shownRows),
         shown,
         reported: rows.length,
         total,
         truncated: shown < (total ?? rows.length),
         valueBasis,
         positionsBasis,
+        ...(insiderCommand ? { form4Insiders: form4 } : {}),
       },
+      ...(choice.length > 0 ? { warnings: choice } : {}),
     }, {
       heading: `${listingHeading(identity)}${cliStyles.muted(facts.map((fact) => `  ·  ${fact}`).join(""))}`,
-      rows: () => rows,
-      columns: [
-        { key: "type", header: "Type" },
+      columns,
+      textColumns: [
+        { key: "ownerType", header: "Type" },
         { key: "name", header: "Holder" },
         { key: "reportDate", header: "Date" },
         { key: "shares", header: "Shares", align: "right", format: formatCountCell },
@@ -992,12 +1232,17 @@ async function runHolders(
           key: "percentHeld",
           header: "% Held",
           align: "right",
-          format: (value) => isFiniteNumber(value) ? formatHolderOwnershipPercent(value) : "",
+          format: (value) => isFiniteNumber(value) ? formatPercentHeld(value) : "",
         },
       ],
-      summary: (holderData: HolderData) => [
-        [valueBasis ? `Value = ${valueBasis}.` : "", positionsBasis ?? "", shareBasisNote ?? ""].filter(Boolean).join(" "),
-        commandName === "insider" && ownerTypes ? insiderSummary(holderData, ownerTypes) : "",
+      // CSV and NDJSON are the HDS report's table and closing lines.
+      tables: {
+        tables: [exportRowsTable("Holders", columns, shownRows)],
+        footer: reportFooterLines({ freshness, notes: notices }),
+      },
+      summary: () => [
+        [valueBasis ? `Value = ${valueBasis}.` : "", positionsBasis ?? "", shareBasisNote ?? "", unvaluedNote ?? ""].filter(Boolean).join(" "),
+        insiderCommand ? insiderSummary(data, ownerTypes, listing, identity, form4) : "",
       ].filter(Boolean).join("\n"),
       empty: `No holders reported for ${listingTitle(identity)}.`,
     });
@@ -1010,6 +1255,7 @@ async function runAnalyst(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
   const raw = requireOneArg(args, "analyst <symbol>", "symbol", ctx);
   await withMarketData(ctx, async (market) => {
     const listing = await requireCliListing(raw, exchangeOption, market, ctx);
+    const venues = loadBareVenues(listing, market);
     const [data, quote] = await Promise.all([
       loadForListing(
         listing, market, ctx, () => market.dataProvider.getAnalystResearch(listing.request.symbol, listing.request.exchange),
@@ -1018,6 +1264,7 @@ async function runAnalyst(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
       loadListingQuote(market.dataProvider, listing),
     ]);
     const identity = listingIdentity(listing, quote);
+    const choice = await listingChoiceNotes(listing, market, quote, venues);
     ctx.printResult({
       data,
       metadata: {
@@ -1029,6 +1276,7 @@ async function runAnalyst(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
       freshness: rowsFreshness(analystRows(data), {
         ...REPORTED_DATA, basis: "analyst ratings", observedKey: "date", oldest: null,
       }, { stale: data.stale === true }),
+      ...(choice.length > 0 ? { warnings: choice } : {}),
     }, {
       heading: listingHeading(identity),
       rows: analystRows,
@@ -1050,6 +1298,7 @@ async function runEvents(rawArgs: string[], ctx: Parameters<CliCommandDef["execu
   const raw = requireOneArg(args, "events <symbol>", "symbol", ctx);
   await withMarketData(ctx, async (market) => {
     const listing = await requireCliListing(raw, exchangeOption, market, ctx);
+    const venues = loadBareVenues(listing, market);
     const [data, quote] = await Promise.all([
       loadForListing(
         listing, market, ctx, () => market.dataProvider.getCorporateActions(listing.request.symbol, listing.request.exchange),
@@ -1058,12 +1307,14 @@ async function runEvents(rawArgs: string[], ctx: Parameters<CliCommandDef["execu
       loadListingQuote(market.dataProvider, listing),
     ]);
     const identity = listingIdentity(listing, quote);
+    const choice = await listingChoiceNotes(listing, market, quote, venues);
     ctx.printResult({
       data,
       metadata: listingMetadata(identity),
       freshness: rowsFreshness(corporateActionRows(data), {
         ...REPORTED_DATA, basis: "corporate actions", observedKey: "date", oldest: null,
       }),
+      ...(choice.length > 0 ? { warnings: choice } : {}),
     }, {
       heading: listingHeading(identity),
       rows: corporateActionRows,
@@ -1111,6 +1362,7 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
     const listing = await requireCliListing(raw, exchangeOption, market, ctx);
     const { symbol, exchange } = listing.request;
     const refresh = ctx.cliOptions.refresh;
+    const venues = loadBareVenues(listing, market);
     const quotePromise = loadListingQuote(market.dataProvider, listing);
     const inputsPromise = loadOptionModelInputs(market.dataProvider, listing, quotePromise, refresh);
     const { result, chain: loaded } = await loadForListing(listing, market, ctx, async () => {
@@ -1140,7 +1392,8 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
       const miss = missingExpiryMessage(listing.key, expirationDate, listed);
       ctx.fail(miss.message, miss.details);
     }
-    const identity = listingIdentity(listing, await quotePromise);
+    const quote = await quotePromise;
+    const identity = listingIdentity(listing, quote);
     const chain = chainWithModelFigures(loaded, inputs);
     // A failed refresh falls back to the stored chain, which can be days old.
     const refreshWarning = result?.refreshError == null ? null
@@ -1150,7 +1403,10 @@ async function runOptions(rawArgs: string[], ctx: Parameters<CliCommandDef["exec
     const modelWarning = inputs.spot == null && (chain.calls.length > 0 || chain.puts.length > 0)
       ? `IV and delta need a current ${listing.key} quote; those columns are blank`
       : null;
-    const warnings = [refreshWarning ?? sessionWarning, modelWarning].filter((warning): warning is string => warning != null);
+    const warnings = [
+      ...await listingChoiceNotes(listing, market, quote, venues),
+      ...[refreshWarning ?? sessionWarning, modelWarning].filter((warning): warning is string => warning != null),
+    ];
     // Dated by the chain's last trade; a chain that failed to refresh is the stored one, stale.
     const freshness = rowsFreshness([], { asOf: chain.asOf ?? null }, {
       ...(chain.dataSource ? { dataSource: chain.dataSource } : {}),
@@ -1226,12 +1482,16 @@ async function runFx(rawArgs: string[], ctx: Parameters<CliCommandDef["execute"]
     const asOf = observed.length > 0 ? new Date(Math.min(...observed)).toISOString() : null;
     const stale = legs.some((leg) => leg != null && (leg.staleAt <= Date.now() || leg.refreshError != null));
     const row = { currency, baseCurrency, rate, asOf, stale, pair, inverse: 1 / rate };
-    ctx.printResult({ data: [row] }, {
-      text: () => {
-        const time = asOf ? `As of ${formatUtcTime(asOf)}` : "";
-        const when = stale ? cliStyles.warning(time ? `${time}, stale` : "Stale") : time && cliStyles.muted(time);
-        return [describeFxRate(request, rate), when].filter(Boolean).join("\n");
-      },
+    // The closing line dates the rate, and says when it is stale, as `fn FXC` does.
+    const freshness = fxPairFreshness(new Map(codes.flatMap((code, index) => {
+      const leg = legs[index];
+      return leg ? [[code, {
+        rate: leg.value,
+        timing: { asOf: leg.asOf, staleAt: leg.staleAt, error: leg.refreshError, delayMinutes: leg.delayMinutes },
+      }] as const] : [];
+    })));
+    ctx.printResult({ data: [row], freshness }, {
+      text: () => describeFxRate(request, rate),
       columns: [
         { key: "currency", header: "Currency" },
         { key: "baseCurrency", header: "Base" },
@@ -1254,24 +1514,55 @@ async function runEarnings(rawArgs: string[], ctx: Parameters<CliCommandDef["exe
     const listings = await Promise.all(symbols.map((symbol) => requireCliListing(
       symbol, exchangeOption, services, ctx, { ownExchangeWins: symbols.length > 1 },
     )));
-    const events = await loadForListing(
-      listings, services, ctx,
-      () => services.dataProvider.getEarningsCalendar(listings.map((listing) => listing.key)),
-      (found) => found.length === 0,
-    );
+    const keys = listings.map((listing) => listing.key);
+    // Each bare symbol's venues cost a search, so a long list (a portfolio check, not a lookup) names none.
+    const venues = new Map(listings.length > MAX_CHOICE_LOOKUPS ? []
+      : listings.map((listing) => [listing, loadBareVenues(listing, services)] as const));
+    let events: EarningsEvent[];
+    try {
+      events = await loadForListing(
+        listings, services, ctx,
+        () => services.dataProvider.getEarningsCalendar(keys),
+        (found) => found.length === 0,
+      );
+    } catch (error) {
+      const failure = earningsCalendarFailure(error, keys);
+      if (failure) ctx.fail(failure);
+      throw error;
+    }
+    const eventOf = (listing: CliListing) => events.find((event) => event.symbol.toUpperCase() === listing.key.toUpperCase());
+    const [abroadNotes, choiceNotes] = await Promise.all([
+      // A listing abroad with no date of its own says so, with its US line's date when that line is the same company.
+      Promise.all(listings.filter((listing) => isListingAbroad(listing) && !eventOf(listing))
+        .map((listing) => noListingCalendarNote(listing, services))),
+      Promise.all(listings.map(async (listing) => {
+        const listed = venues.get(listing);
+        return listed ? earningsChoiceNote(listing, eventOf(listing), await listed) : null;
+      })),
+    ]);
+    const noCalendar = abroadNotes.join("\n");
+    // Text prints the listings without a calendar under the table; other formats carry them as warnings.
+    const warnings = [
+      ...listings.flatMap(listingReadNotes),
+      ...choiceNotes.filter((note): note is string => !!note),
+      ...ctx.cliOptions.format === "text" ? [] : abroadNotes,
+    ];
     ctx.printResult({
       data: events,
       freshness: rowsFreshness(earningsRows(events), { status: "not-a-feed", basis: "calendar", observedKey: "date", oldest: null }),
+      ...(warnings.length > 0 ? { warnings } : {}),
     }, {
       rows: earningsRows,
       columns: [
         { key: "date", header: "Date" },
+        { key: "status", header: "Status" },
         { key: "symbol", header: "Symbol" },
         { key: "name", header: "Name" },
         { key: "timing", header: "Timing" },
         { key: "epsEstimate", header: "EPS Est", align: "right", format: formatEpsCell },
         { key: "epsActual", header: "EPS", align: "right", format: formatEpsCell },
       ],
+      ...(noCalendar ? { empty: noCalendar, footnote: noCalendar } : {}),
     });
   });
 }
@@ -1312,7 +1603,7 @@ export const marketDataCliCommands: BuiltinCliCommandDef[] = [
       sections: [{
         title: "Bars",
         lines: [
-          `Each range comes in one bar size: ${historyIntervalsByRange()}. The line under the heading, and the --json metadata, give the currency, the bar size actually served, the first and last bar and the bar count. A warning says when the bars are coarser, or start later, than the range asked for.`,
+          `Each range comes in one bar size: ${historyIntervalsByRange()}. The line under the heading, and the --json metadata, give the currency, the bar size actually served, the first and last bar and the bar count. A warning says when the bars are coarser, or start later, than the range asked for, and for a coin, which trades every day, names each day it has no bar for.`,
           "A bar whose prices contradict each other (high below the open or close, or low above them) is left blank and flagged, such as high<open, with the count in a warning. Every exported row (--csv, --ndjson, --json) carries currency, interval and flag.",
         ],
       }],
@@ -1472,7 +1763,13 @@ export const marketDataCliCommands: BuiltinCliCommandDef[] = [
         { flags: "--history", description: "With --form 13d, 13g or all, every report newest first instead of the latest per filer" },
         EXCHANGE_OPTION,
       ],
-      examples: ["holders AAPL", "holders SAN:EPA", "holders CAR --form all", "holders CAR --form 13g --history --json"],
+      sections: [{
+        title: "Output",
+        lines: [
+          "Holders run largest value first, as in fn HDS. --csv and --json carry the HDS report's columns: values in the currency the header names, shares, and the quarter's change and the stake in percent (0.59 is 0.59%).",
+        ],
+      }],
+      examples: ["holders AAPL", "holders SAN:EPA", "holders SAN --csv", "holders CAR --form all", "holders CAR --form 13g --history --json"],
     },
     execute: (args, ctx) => runHolders(args, ctx, "holders"),
   },
@@ -1519,15 +1816,21 @@ export const marketDataCliCommands: BuiltinCliCommandDef[] = [
   },
   {
     name: "news",
-    description: "Fetch market headlines, or news for one symbol",
+    description: "Fetch market headlines, news for one symbol, or stories matching text",
     help: {
       group: CLI_COMMAND_GROUPS.companyData,
-      usage: ["news [symbol] [--feed <feed>]"],
+      usage: ["news [symbol] [--feed <feed>]", "news <query>"],
       options: [
         { flags: "--feed <feed>", description: "latest, top, or breaking for market news (default latest)" },
         EXCHANGE_OPTION,
       ],
-      examples: ["news", "news TSLA", "news SAN:EPA", "news --feed top --limit 10"],
+      sections: [{
+        title: "Text",
+        lines: [
+          "Several words, in quotes or not, search the stories that mention them. So does a single word of three letters or more that no listing answers to, and a futures board code such as TTF, a gas benchmark rather than a ticker. A real ticker always gives its own news. The best matches print newest first, 20 unless --limit says otherwise; a search takes neither --feed nor --exchange.",
+        ],
+      }],
+      examples: ["news", "news TSLA", "news SAN:EPA", "news TTF", "news \"european gas\"", "news --feed top --limit 10"],
     },
     execute: runNews,
   },