gloomberb 0.18.2 → 0.18.3

package/src/cli/commands/ticker.ts

@@ -36,7 +36,8 @@ import {
 import type { FuturesContractTermsPayload } from "../../api-client/futures-curve";
 import { changeBasisJson, quoteChangeBasis, quotePreviousCloseDate } from "../../market-data/market/change-basis";
 import { futuresContractLines, futuresSettleText, isFuturesInstrument, loadFuturesContractTerms, minorUnitPricePer } from "../../market-data/futures-contract";
-import { currencyCodeLabel } from "../../utils/currency-units";
+import { currencyCodeLabel, heldCurrencyUnit } from "../../utils/currency-units";
+import { quotedFxPair } from "../../utils/currency-pair";
 import type { AppConfig } from "../../types/config";
 import type { DeclaredDividendAction, FinancialStatement, Quote, TickerFinancials } from "../../types/financials";
 import { atRegularSessionPrice, regularSessionValuationPrice } from "../../market-data/quotes/regular-session-valuation";
@@ -73,6 +74,7 @@ import {
   resolveCliListing, type CliListing, type ListingDataRequest,
 } from "../listing-arg";
 import { movedAwayChange } from "../../tickers/ticker-changes";
+import { companyMemberships, loadCompanyMemberships, type CompanyMemberships, type ListMembership } from "../issuer-membership";
 import { isNotATickerMessage } from "../not-a-ticker";
 import { sharesOutstandingInReceipts } from "../../utils/depositary-receipt";
 import { cliFreshnessFooter } from "../result";
@@ -301,7 +303,7 @@ function shouldFetchSecFilings(
 }
 
 async function appendTickerPositions(lines: string[], tickerFile: TickerRecord | null, quote: TickerFinancials["quote"],
-  config: AppConfig, toBase: ReportBaseConverter): Promise<void> {
+  config: AppConfig, toBase: ReportBaseConverter, rates: ReportRateNotes): Promise<void> {
   const quoteCurrency = quote?.currency?.trim() || tickerFile?.metadata.currency?.trim() || "";
   const codes = writesCurrencyCodes(config);
   const money = codes ? formatCurrencyCode : formatCurrency;
@@ -324,9 +326,10 @@ async function appendTickerPositions(lines: string[], tickerFile: TickerRecord |
       if (quoteCurrency && currentPrice != null) converted.add(quoteCurrency.toUpperCase());
       const baseMetrics = getPortfolioPositionMetrics({ ...tickerFile, metadata: { ...tickerFile.metadata, positions: [position] } }, undefined, quoteCurrency,
         { currency: config.baseCurrency, convert: value => value * positionRate }, quote);
-      // A cost bought at an entered rate into the base currency converts at it, as its P&L does; any other at today's.
+      // A cost bought at an entered rate into the base currency converts at it, as its P&L does, and says so; any other at today's.
+      const boughtRate = positionCurrency ? lotCostFxRate(position, positionCurrency, config.baseCurrency) : null;
       const costBasisBase = !positionCurrency ? Number.NaN
-        : lotCostFxRate(position, positionCurrency, config.baseCurrency) !== null ? baseMetrics.signedCost
+        : boughtRate !== null ? baseMetrics.signedCost
         : await toBase(metrics.signedCost, positionCurrency);
       const marketValueBase = resolvePortfolioMarketValue(baseMetrics, currentPriceBase)?.net ?? Number.NaN;
       const selectedPnl = resolvePortfolioPositionPnl(baseMetrics, currentPriceBase);
@@ -339,7 +342,8 @@ async function appendTickerPositions(lines: string[], tickerFile: TickerRecord |
           "Position",
           `${formatMarketQuantity(metrics.totalShares, { assetCategory: tickerFile.metadata.assetCategory, multiplier: position.multiplier, priceBasis: metrics.priceBasis, quantityCurrency: positionCurrency })} ${metrics.priceBasis === "percent-of-par" ? "@" : `${tickerFile.metadata.assetCategory === "BOND" ? "units" : contracts ? "contracts" : "shares"} @`} ${positionCurrency ? formatMarketCostWithCurrency(position.avgCost, positionCurrency, { assetCategory: tickerFile.metadata.assetCategory, multiplier: position.multiplier, priceBasis: metrics.priceBasis, currencyCode: codes }) : "—"}`,
         ],
-        ["Cost Basis", money(costBasisBase, config.baseCurrency)],
+        ["Cost Basis", `${money(costBasisBase, config.baseCurrency)}${boughtRate !== null
+          ? ` (${formatFxRate(boughtRate)} ${config.baseCurrency.trim().toUpperCase()} per ${positionCurrency} when bought)` : ""}`],
         ["Market Value", money(marketValueBase, config.baseCurrency)],
         [
           selectedPnl.basis === "broker-snapshot" ? "Broker P&L" : "P&L",
@@ -354,7 +358,7 @@ async function appendTickerPositions(lines: string[], tickerFile: TickerRecord |
         lines.push("");
       }
     }
-    for (const note of conversionNotes(toBase, converted)) lines.push(cliStyles.muted(note));
+    for (const note of conversionNotes(toBase, converted, rates)) lines.push(cliStyles.muted(note));
   }
 }
 
@@ -372,14 +376,41 @@ export function writesCurrencyCodes(config: Pick<AppConfig, "baseCurrency"> | un
 }
 
 /**
- * "CAD at USD/CAD 1.40623, as of 2026-10-21 04:46 UTC.": the rate and its
- * date for each currency in `currencies` the report converted into the base
- * currency, so a converted figure is never without what it was converted at.
+ * What the report's rate notes have said and must say: each currency's rate
+ * is stated once, under the first section that converted it, and a lot whose
+ * cost converts at the rate entered when it was bought is left out of it.
  */
-function conversionNotes(toBase: ReportBaseConverter, currencies: ReadonlySet<string>): string[] {
+interface ReportRateNotes {
+  /** Currencies whose rate a note already gave. */
+  noted: Set<string>;
+  /** Currencies of lots whose Cost Basis is at their own entered rate. */
+  boughtAt: ReadonlySet<string>;
+}
+
+/** The currencies of the shown lots whose cost converts into the base currency at the rate they were bought at. */
+function boughtRateCurrencies(tickerFile: TickerRecord | null, quoteCurrency: string, baseCurrency: string): Set<string> {
+  return new Set((tickerFile?.metadata.positions ?? []).flatMap((position) => {
+    const currency = (position.currency || quoteCurrency).trim();
+    return position.shares !== 0 && currency && lotCostFxRate(position, currency, baseCurrency) !== null ? [currency.toUpperCase()] : [];
+  }));
+}
+
+/**
+ * "CAD figures at USD/CAD 1.40623, as of 2026-10-21 04:46 UTC.": the rate
+ * and its date for each currency in `currencies` the report converted into
+ * the base currency, as markets quote the pair (USD/JPY, not JPY/USD), so a
+ * converted figure is never without what it was converted at. A rate already
+ * stated is not repeated, and a cost basis at its own rate is excepted.
+ */
+function conversionNotes(toBase: ReportBaseConverter, currencies: ReadonlySet<string>, rates: ReportRateNotes): string[] {
   return (toBase.conversions?.() ?? [])
-    .filter((conversion) => currencies.has(conversion.currency) && conversion.currency !== conversion.baseCurrency)
-    .map(({ currency, baseCurrency, rate, asOf }) => `${baseCurrency} figures at ${currency}/${baseCurrency} ${formatFxRate(rate)}${asOf != null ? `, as of ${formatTimestamp(asOf)}` : ""}.`);
+    .filter((conversion) => currencies.has(conversion.currency) && conversion.currency !== conversion.baseCurrency && !rates.noted.has(conversion.currency))
+    .map(({ currency, baseCurrency, rate, asOf }) => {
+      rates.noted.add(currency);
+      const quoted = quotedFxPair(currency, baseCurrency, rate);
+      const except = rates.boughtAt.has(currency) ? ", except a cost basis at the rate it was bought at" : "";
+      return `${baseCurrency} figures at ${quoted.pair} ${formatFxRate(quoted.rate)}${asOf != null ? `, as of ${formatTimestamp(asOf)}` : ""}${except}.`;
+    });
 }
 
 /** A source's enterprise value is in the units of the capitalization it reports beside it,
@@ -947,8 +978,11 @@ export async function buildTickerReport({
   distributions = null,
   statementFilings = null,
   bondFund = null,
+  memberships,
 }: {
   symbol: string;
+  /** The lists holding the company, by any of its listings (loadCompanyMemberships); the saved listing's own lists when absent. */
+  memberships?: CompanyMemberships;
   /** The filings behind the latest statements, and a newer quarter's results release. */
   statementFilings?: StatementFilingsReport | null;
   /** A bond fund's SEC yield, yield to worst and duration (loadReportBondFacts). */
@@ -981,6 +1015,10 @@ export async function buildTickerReport({
   const baseQuoteOptions = quoteFormatOptions(quote, tickerFile?.metadata.assetCategory, financials.quoteMetadata?.instrumentType);
   const baseCurrency = config.baseCurrency.trim().toUpperCase();
   const codes = writesCurrencyCodes(config);
+  const rates: ReportRateNotes = {
+    noted: new Set(),
+    boughtAt: boughtRateCurrencies(tickerFile, quote?.currency?.trim() || tickerFile?.metadata.currency?.trim() || "", config.baseCurrency),
+  };
   // Pad money prices to the currency's minor unit so a range reads £35.10 - £35.485, never past it (JPY has none).
   const quoteOptions = withCurrencyMinorDigits(codes ? { ...baseQuoteOptions, currencyCode: true } : baseQuoteOptions, quote?.currency);
   const lines: string[] = [];
@@ -1015,14 +1053,15 @@ export async function buildTickerReport({
     lines.push(cliStyles.muted(metadataParts.join(METADATA_SEPARATOR)));
   }
 
-  const portfolioNames = tickerFile ? formatPortfolioNames(config, tickerFile.metadata.portfolios) : [];
-  const watchlistNames = tickerFile ? formatWatchlistNames(config, tickerFile.metadata.watchlists) : [];
+  // A list that holds the company as another of its listings says which: "Watchlists R (as RCI.B:TSX)".
+  const lists = memberships ?? companyMemberships(config, tickerFile, [], null);
+  const listNames = (held: readonly ListMembership[]) => held.map((list) => list.via ? `${list.name} (as ${list.via})` : list.name).join(", ");
   const membershipParts = [
-    portfolioNames.length > 0
-      ? `Portfolios ${portfolioNames.join(", ")}`
+    lists.portfolios.length > 0
+      ? `Portfolios ${listNames(lists.portfolios)}`
       : undefined,
-    watchlistNames.length > 0
-      ? `Watchlists ${watchlistNames.join(", ")}`
+    lists.watchlists.length > 0
+      ? `Watchlists ${listNames(lists.watchlists)}`
       : undefined,
   ].filter((part): part is string => !!part);
   if (membershipParts.length > 0) {
@@ -1036,10 +1075,13 @@ export async function buildTickerReport({
   // with the base currency's figure after them when it differs: 627.2B USD (878.15B CAD).
   const convertedCurrencies = new Set<string>();
   const inBase = async (value: number, currency: string): Promise<string> => {
-    if (currency.trim().toUpperCase() === baseCurrency) return "";
-    const converted = await toBase(value, currency);
+    // A minor unit converts as the hundredth of its currency it is: 2.75T GBp is 27.5B GBP, never 2.75T GBP.
+    const unit = heldCurrencyUnit(currency);
+    if (!unit.currency || (unit.currency === baseCurrency && unit.divisor === 1)) return "";
+    const major = value / unit.divisor;
+    const converted = unit.currency === baseCurrency ? major : await toBase(major, unit.currency);
     if (!Number.isFinite(converted)) return "";
-    convertedCurrencies.add(currency.trim().toUpperCase());
+    if (unit.currency !== baseCurrency) convertedCurrencies.add(unit.currency);
     return ` (${formatCompact(converted)} ${baseCurrency})`;
   };
   const marketCapText = capitalization
@@ -1048,8 +1090,7 @@ export async function buildTickerReport({
   // Shown in the same currency as the market cap, so the two can be compared.
   const enterpriseValue = reportedEnterpriseValue(priced.fundamentals);
   const evCurrency = enterpriseValueCurrency(quote, fundamentals);
-  // A minor unit such as GBp stays as reported: the converter would read it as the major currency.
-  const enterpriseValueText = `${formatReportedMoney(enterpriseValue, evCurrency)}${enterpriseValue != null && evCurrency && /^[A-Z]{3}$/.test(evCurrency)
+  const enterpriseValueText = `${formatReportedMoney(enterpriseValue, evCurrency)}${enterpriseValue != null && evCurrency
     ? await inBase(enterpriseValue, evCurrency) : ""}`;
 
   if (quote) {
@@ -1099,7 +1140,7 @@ export async function buildTickerReport({
   const beforeFundamentals = lines.length;
   appendMetricSection(lines, "Fundamentals", metricLines(metrics));
   for (const note of fundamentalsNotes(priced, metrics, quote?.currency)) lines.push(cliStyles.muted(note));
-  if (lines.length > beforeFundamentals) for (const note of conversionNotes(toBase, convertedCurrencies)) lines.push(cliStyles.muted(note));
+  if (lines.length > beforeFundamentals) for (const note of conversionNotes(toBase, convertedCurrencies, rates)) lines.push(cliStyles.muted(note));
   // Where a fund's facts would go: under its fundamentals, or in their place.
   const fund = fundFactsNote(quote?.symbol ?? symbol,
     quote?.tradingExchangeName || listingExchange || quote?.listingExchangeName || quote?.exchangeName || tickerFile?.metadata.exchange, financials, tickerFile);
@@ -1159,7 +1200,7 @@ export async function buildTickerReport({
     link: filing.filingUrl,
   })), hiddenFilingsNote(hiddenSecFilings));
 
-  await appendTickerPositions(lines, tickerFile, quote, config, toBase);
+  await appendTickerPositions(lines, tickerFile, quote, config, toBase, rates);
 
   return lines.join("\n");
 }
@@ -1178,9 +1219,11 @@ function buildTickerStructuredData({
   distributions,
   statementFilings,
   bondFund = null,
+  memberships,
 }: {
   symbol: string;
   listing: CliListing;
+  memberships: CompanyMemberships;
   statementFilings: StatementFilingsReport | null;
   bondFund?: FundBondFacts | null;
   futuresContract: FuturesContractTermsPayload | null;
@@ -1236,6 +1279,8 @@ function buildTickerStructuredData({
       watchlists: formatWatchlistNames(config, tickerFile.metadata.watchlists),
       positions: tickerFile.metadata.positions,
     } : null,
+    // The lists holding the company by any of its listings; `via` names the other listing a list holds it as.
+    memberships,
     fundamentals: financials.fundamentals || priceReturns.return1Y != null || priceReturns.return3Y != null ? exportedDividendFundamentals(exportedFundamentals({
       ...priced.fundamentals,
       ...priceReturns,
@@ -1368,6 +1413,15 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
       quarter: latestFinancialPeriod(resolvedFinancials.quarterlyStatements, (row) => row.date),
       annual: latestFinancialPeriod(resolvedFinancials.annualStatements, (row) => row.date),
     });
+    // A list holding the company as another of its listings counts (a list of RCI.B:TSX holds RCI); read beside the rest. It never fails.
+    const membershipsLoad = loadCompanyMemberships({
+      config,
+      own: tickerFile,
+      symbol: listing.symbol,
+      exchange: canonicalExchange(listing.exchange || quote?.listingExchangeName || quote?.exchangeName || tickerFile?.metadata.exchange),
+      loadTickers: () => store.loadAllTickers(),
+      dataProvider,
+    });
     const [notesResult, newsResult, secFilingsResult] = await Promise.allSettled([
       notesFiles.load(tickerFile?.metadata.ticker ?? normalized),
       dataProvider.getNews({
@@ -1401,6 +1455,7 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
     const coinNote = listing.exchange ? null
       : notTheCoinNote(listing.symbol, quote ?? (tickerFile ? { name: tickerFile.metadata.name, instrumentType: tickerFile.metadata.assetCategory } : null));
     const listingNote = [choiceNote, coinNote].filter((note): note is string => !!note).join("\n") || undefined;
+    const memberships = await membershipsLoad;
     if (dependencies.printResult) {
       const warnings = [choiceNote, coinNote, quoteNote].filter((note): note is string => !!note);
       dependencies.printResult({
@@ -1420,6 +1475,7 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
           distributions: await distributions,
           statementFilings: await statementFilings,
           bondFund: await bondFund,
+          memberships,
         }),
       });
       return;
@@ -1442,6 +1498,7 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
         distributions: await distributions,
         statementFilings: await statementFilings,
         bondFund: await bondFund,
+        memberships,
     }));
     if (freshness) console.log(`\n${cliFreshnessFooter(freshness)}`);
   });

package/src/cli/help.ts

@@ -58,7 +58,7 @@ const GLOBAL_OPTIONS: Array<[string, string]> = [
 
 const EXIT_CODES: Array<[string, string]> = [
   [String(CLI_EXIT_CODES.ok), "Success"],
-  [String(CLI_EXIT_CODES.error), "Failed: bad input, no data found or a failed check"],
+  [String(CLI_EXIT_CODES.error), "Failed: bad input, no data found or a failed check. fn exits 0 on partial data with warnings; --json ok is false exactly when this is 1"],
   [String(CLI_EXIT_CODES.unusableShot), "shot --strict saved an image of a pane with no usable data"],
 ];
 

package/src/cli/index.ts

@@ -190,8 +190,16 @@ export function createCoreCliCommands(
           "fn WEI --csv --section europe > europe.csv",
           "fn 13F AAPL --view=ticker-holdings",
           "fn OVME --spot 100 --strike 100 --days 30 --volatility 25",
+          "fn HIVG SPY --event fomc --offset -6 --lookback ALL --csv",
           "fn AUCT --explain",
         ],
+        sections: [{
+          title: "Exit status",
+          lines: [
+            "0 when the report has data for what was asked, partial data with warnings about the rest included; 1 when it has none (an empty report, or rows with no value for a listing that has nothing) or the input is bad. --json ok is false exactly when the exit status is 1.",
+            "CSV headers are the same for every symbol: a reason a figure is missing goes to the status column, never into a number cell.",
+          ],
+        }],
       },
       execute: async (args, ctx) => {
         requirePaneFunctionTarget(args, "fn", ctx);

package/src/cli/issuer-membership.ts

@@ -0,0 +1,103 @@
+import type { AppConfig } from "../types/config";
+import type { DataProvider } from "../types/data-provider";
+import type { TickerRecord } from "../types/ticker";
+import { canonicalExchange, isUsListingExchange, parsePublicTickerKey } from "../utils/exchanges";
+import { logFailure } from "../utils/log-failure";
+import { savedListingName } from "./listing-arg";
+
+/** A list holding the company: its name, and the other saved listing it holds the company as (null for the listing asked about). */
+export interface ListMembership {
+  name: string;
+  /** RCI.B:TSX when the list holds Rogers as its Toronto line and the report is of RCI. */
+  via: string | null;
+}
+
+export interface CompanyMemberships {
+  portfolios: ListMembership[];
+  watchlists: ListMembership[];
+}
+
+/**
+ * A listing as Gloom Cloud writes an issuer's listings: the bare ticker on a
+ * US venue or none (RCI), SYMBOL:EXCHANGE elsewhere (RCI.B:TSX), with a
+ * share class's dash or slash as a dot (BRK-B is BRK.B).
+ */
+export function issuerListingKey(symbol: string, exchange?: string): string {
+  const parsed = parsePublicTickerKey(symbol);
+  const venue = parsed.exchange ?? canonicalExchange(exchange);
+  const code = parsed.symbol.toUpperCase().replace(/[-/]/g, ".");
+  return venue && !isUsListingExchange(venue) ? `${code}:${venue}` : code;
+}
+
+function names(config: AppConfig, ids: readonly string[], kind: "portfolios" | "watchlists"): Map<string, string> {
+  const collections: ReadonlyArray<{ id: string; name: string }> = config[kind];
+  return new Map(ids.flatMap((id) => {
+    const name = collections.find((collection) => collection.id === id)?.name;
+    return name ? [[id, name] as const] : [];
+  }));
+}
+
+/**
+ * The portfolios and watchlists that hold a company, whichever of its
+ * listings they saved: the listing's own lists, then those holding another
+ * of `issuerListings` (its keys as `issuerListingKey` writes them), each
+ * once and saying which listing it holds. A restricted list holding RCI.B:TSX
+ * holds Rogers, which also trades as RCI in New York. Without the company's
+ * listings, only the listing's own lists.
+ */
+export function companyMemberships(
+  config: AppConfig,
+  own: TickerRecord | null,
+  saved: readonly TickerRecord[],
+  issuerListings: readonly string[] | null,
+): CompanyMemberships {
+  const listings = new Set(issuerListings ?? []);
+  const ownKey = own ? savedListingName(own).key : null;
+  const others = listings.size === 0 ? [] : saved.filter((ticker) =>
+    savedListingName(ticker).key !== ownKey
+    && listings.has(issuerListingKey(ticker.metadata.ticker, ticker.metadata.exchange)));
+  const collect = (kind: "portfolios" | "watchlists"): ListMembership[] => {
+    const held = new Map<string, ListMembership>();
+    for (const [id, name] of names(config, own?.metadata[kind] ?? [], kind)) held.set(id, { name, via: null });
+    for (const ticker of others) {
+      for (const [id, name] of names(config, ticker.metadata[kind], kind)) {
+        if (!held.has(id)) held.set(id, { name, via: savedListingName(ticker).key });
+      }
+    }
+    return [...held.values()];
+  };
+  return { portfolios: collect("portfolios"), watchlists: collect("watchlists") };
+}
+
+/**
+ * `companyMemberships` for a listing, asking Gloom Cloud for the company's
+ * other listings only when another saved listing is in a list at all. A
+ * failed lookup leaves the listing's own lists.
+ */
+export async function loadCompanyMemberships({
+  config,
+  own,
+  symbol,
+  exchange,
+  loadTickers,
+  dataProvider,
+}: {
+  config: AppConfig;
+  own: TickerRecord | null;
+  /** The listing the report is of, and its venue (RCI, NYSE). */
+  symbol: string;
+  exchange: string;
+  loadTickers: () => Promise<TickerRecord[]>;
+  dataProvider: Pick<DataProvider, "getIssuerListings">;
+}): Promise<CompanyMemberships> {
+  const ownKey = own ? savedListingName(own).key : null;
+  const saved = await Promise.resolve().then(loadTickers)
+    .catch(logFailure("cli.issuer-membership", "Reading saved listings failed", [] as TickerRecord[]));
+  const listed = saved.filter((ticker) => savedListingName(ticker).key !== ownKey
+    && (ticker.metadata.portfolios.length > 0 || ticker.metadata.watchlists.length > 0));
+  const { getIssuerListings } = dataProvider;
+  if (listed.length === 0 || !getIssuerListings) return companyMemberships(config, own, [], null);
+  const issuer = await Promise.resolve().then(() => getIssuerListings.call(dataProvider, symbol, exchange))
+    .catch(logFailure("cli.issuer-membership", "Reading the company's listings failed", null));
+  return companyMemberships(config, own, listed, issuer?.listings.map((listing) => issuerListingKey(listing.symbol, listing.exchange)) ?? null);
+}

package/src/cli/listing-arg.ts

@@ -836,6 +836,13 @@ export async function loadSavedListing(store: ListingStore, listing: ListingArg)
   return null;
 }
 
+/** A row saved under a vendor's suffixed key (RY.TO) for the listing it was read as: on that venue, or on none it names. */
+async function loadSuffixedRow(store: ListingStore, key: string, exchange: string): Promise<TickerRecord | null> {
+  const ticker = await store.loadTicker(key);
+  const savedExchange = canonicalExchange(ticker?.metadata.exchange);
+  return ticker && (!savedExchange || savedExchange === exchange) ? ticker : null;
+}
+
 export interface CliListing extends ListingArg {
   saved: TickerRecord | null;
   /**
@@ -895,7 +902,11 @@ export async function resolveCliListing(
   deps: ListingDeps,
   options: {
     ownExchangeWins?: boolean;
-    /** Read a venue suffix (RY.TO) as the listing its quote names (RY:TSX): `fn` and `shot`, whose functions read data by venue. */
+    /**
+     * Read a venue suffix (RY.TO) as the listing its quote names (RY:TSX).
+     * Only pane functions ask for it (`applyListingArgument`, which `fn` and
+     * `shot` run through), as their data is read by venue.
+     */
     venueSuffix?: boolean;
   } = {},
 ): Promise<CliListing> {
@@ -913,6 +924,8 @@ export async function resolveCliListing(
   const pair = parsed.exchange ? null : await readAmbiguousCurrencyPair(parsed.symbol, deps);
   if (pair) parsed = { symbol: pair, exchange: "", key: pair };
   const suffixed = pair || named || !options.venueSuffix ? null : await readVenueSuffix(parsed, deps);
+  // The row may be saved under the suffixed key itself: a link or a layout's key is kept as it came.
+  const typedKey = suffixed ? parsed.symbol : null;
   if (suffixed) parsed = parsed.readAs ? { ...suffixed, readAs: `${parsed.readAs} ${suffixed.readAs}` } : suffixed;
   try {
     await checkListingExchange(parsed, deps);
@@ -922,7 +935,7 @@ export async function resolveCliListing(
     parsed = market;
   }
   let listing = await settleSharedCode(parsed, deps);
-  const saved = await loadSavedListing(deps.store, listing);
+  const saved = await loadSavedListing(deps.store, listing) ?? (typedKey ? await loadSuffixedRow(deps.store, typedKey, listing.exchange) : null);
   // A code nothing could read stays the venue it is saved on.
   const savedExchange = canonicalExchange(saved?.metadata.exchange);
   if (listing.sharedCode && savedExchange) listing = { symbol: listing.symbol, exchange: savedExchange, key: `${listing.symbol}:${savedExchange}` };

package/src/cli/name-entries.ts

@@ -6,26 +6,65 @@ import { splitSymbolWords } from "./symbol-args";
 import { isProviderBusy } from "../sources/provider-errors";
 
 /**
- * The entries of a list (`splitSymbolArgs`) as the symbols a command
- * resolves. An entry with a space in it is a company's name when search finds
- * the company (`Whirlpool Corporation`), and stays whole for its listing to
- * say what it was read as; otherwise it is its words, each a symbol, as a
- * pasted line always was (`brk.b bf-b`). Only those entries cost a search.
- * One search was too busy to look up also stays whole, so its lookup says so
- * instead of resolving its words as symbols of other companies.
+ * The entries of a list (`splitSymbolArgs`, or a file's lines) as the symbols
+ * a command resolves. An entry with a space in it is a company's name when
+ * search finds the company (`Whirlpool Corporation`, `philip morris intl`),
+ * and stays whole for its listing to say what it was read as. One search
+ * finds no company for is its words, each a symbol, when each is written as
+ * a symbol or has a quote (`AAPL MSFT`, `brk.b bf-b`, `aapl msft` on a
+ * pasted line), and otherwise stays whole, a name nothing lists: its words
+ * are not taken for other companies' symbols (INTL, a fund, from a misspelt
+ * `phillip morris intl`). Only those entries cost a search. One search was
+ * too busy to look up also stays whole, so its lookup says so instead of
+ * resolving its words as symbols of other companies.
  */
 export async function readNameEntries(
   entries: readonly string[],
-  dataProvider: Pick<DataProvider, "search">,
+  dataProvider: Pick<DataProvider, "search"> & Partial<Pick<DataProvider, "getQuotesBatch" | "getQuote">>,
 ): Promise<string[]> {
-  const read = await Promise.all(entries.map(async (entry) => (
+  const read = await Promise.all(entries.map(async (entry) => {
     // A terminal's code for a listing ("JPM US Equity") is one entry, like a company's name.
-    await readTerminalCodeArg(dataProvider, entry) || (isCompanyNameInput(entry) && await findListingOfCompanyName(dataProvider, entry).catch(busyAsFound))
-      ? [entry] : splitSymbolWords([entry])
-  )));
+    if (await readTerminalCodeArg(dataProvider, entry)) return [entry];
+    if (!isCompanyNameInput(entry)) return splitSymbolWords([entry]);
+    if (await findListingOfCompanyName(dataProvider, entry).catch(busyAsFound)) return [entry];
+    const words = splitSymbolWords([entry]);
+    return await wordsAreSymbols(words, dataProvider) ? words : [entry];
+  }));
   return read.flat();
 }
 
+/** A word typed as a ticker is: in capitals (AAPL, 7203.T), with a venue or class mark (brk.b, bf-b, SAN:EPA), or after a $. */
+function writtenAsSymbol(word: string): boolean {
+  return /^\$|[:.\-/=^]/.test(word) || /\d/.test(word) || (/\p{Lu}/u.test(word) && !/\p{Ll}/u.test(word));
+}
+
+/**
+ * Whether the words of an entry search found no company for are symbols:
+ * each written as one (2222, BRK.B) or else with a quote, the others asked in
+ * one batch (`2222 amd pltr`). A batch that fails says nothing, and the
+ * entry stays a name.
+ */
+async function wordsAreSymbols(
+  words: readonly string[],
+  dataProvider: Partial<Pick<DataProvider, "getQuotesBatch" | "getQuote">>,
+): Promise<boolean> {
+  const symbols = words.filter((word) => !writtenAsSymbol(word)).map((word) => word.replace(/^\$/, "").toUpperCase());
+  if (symbols.length === 0) return true;
+  if (dataProvider.getQuotesBatch) {
+    const results = await dataProvider.getQuotesBatch(symbols.map((symbol) => ({ symbol, exchange: "" })))
+      .catch(logFailure("cli.name-entries", "Read quotes for a pasted line failed", []));
+    return results.length === symbols.length && results.every(({ quote }) => !!quote);
+  }
+  // A source without batches is asked a quote at a time: the few words not written as symbols.
+  const { getQuote } = dataProvider;
+  if (!getQuote) return false;
+  const quoted = await Promise.all(symbols.map((symbol) => getQuote(symbol, "").then(
+    (quote) => !!quote,
+    logFailure("cli.name-entries", "Read a quote for a pasted line failed", false),
+  )));
+  return quoted.every(Boolean);
+}
+
 /** `findListingOfCompanyName`'s busy answer as a name to keep whole, any other failure as it is. */
 function busyAsFound(error: unknown): true {
   if (isProviderBusy(error)) return true;

package/src/cli/pane-functions/capabilities.ts

@@ -18,6 +18,8 @@ export interface PaneFunctionCapability {
   botSafe: boolean;
   tickerCardinality: PaneFunctionTickerCardinality;
   aliases: string[];
+  /** Words that are no code but ask for this function's data: `fn` and `catalog` answer them with it. */
+  suggestFor?: string[];
   intents: string[];
   outputKind: string;
   reportReadiness: PaneFunctionReadiness;

package/src/cli/pane-functions/catalog.ts

@@ -210,6 +210,21 @@ export function nearFunctionCodes(
     .sort((left, right) => left.code.localeCompare(right.code));
 }
 
+/**
+ * The functions a word that is no code asks for (`IVOL`, `IV`: HIVG and
+ * OVDV), as their `discovery.suggestFor` lists it, each by its code.
+ */
+export function suggestedFunctionCodes(registry: PaneFunctionCatalog, name: string): NearFunctionCode[] {
+  const wanted = normalizeLookupToken(name);
+  if (!wanted) return [];
+  return [...registry.paneTemplates.values()].flatMap((template) => {
+    const pane = registry.panes.get(template.paneId);
+    const words = pane ? getHeadlessPaneDefinition(template, pane)?.discovery?.suggestFor ?? [] : [];
+    const code = template.shortcut?.prefix;
+    return code && words.some((word) => normalizeLookupToken(word) === wanted) ? [{ code: code.toUpperCase(), label: template.label }] : [];
+  }).sort((left, right) => left.code.localeCompare(right.code));
+}
+
 function sampleArgForTemplate(template: PaneTemplateDef): string {
   switch (template.shortcut?.argKind) {
     case "ticker":
@@ -391,6 +406,7 @@ function scorePaneCatalogEntry(entry: PaneCatalogEntry, query: string): CatalogM
     entry.token,
     entry.shortcut,
     ...entry.aliases,
+    ...entry.capability.suggestFor ?? [],
     entry.templateId,
     entry.paneId,
   ].filter((value): value is string => !!value).map((value) => normalizeLookupToken(value));

package/src/cli/pane-functions/dom.ts

@@ -222,7 +222,8 @@ export async function buildDomPaneReportFromRender(
   const truncated = truncationReasons.length > 0
     || (result.render.reportTruncationReasons ? false : result.render.truncated);
   const failureReason = renderedFailureReason(result, rows);
-  const unavailableSymbols = failureReason && result.symbols.length > 0 ? result.symbols : [];
+  // A pane that drew rows beside an error or empty marker ("Quote unavailable.") has data: only one with none has no data for its symbols.
+  const unavailableSymbols = failureReason && rows.length === 0 && result.symbols.length > 0 ? result.symbols : [];
   // What the view leaves out and how to see more, such as OMON's strikes outside its window.
   const rendered = renderedReportNotices(result.render.semanticUi ?? []);
   const notices = [...(resolved.pane.reportNotices?.(resolved.instance.settings ?? {}) ?? []), ...rendered.notices];

package/src/cli/pane-functions/headless.ts

@@ -89,17 +89,36 @@ function normalizeSymbolList(value: string): string[] {
   return symbols;
 }
 
-function validateSymbolCount(
+const COUNT_WORDS = ["zero", "one", "two", "three", "four", "five"];
+const EXAMPLE_TICKERS = ["SPY", "QQQ", "IWM", "DIA", "TLT"];
+
+/**
+ * What a function that compares several tickers answers fewer: how many it
+ * needs and a command that runs, the reader's own tickers first (`CMP needs
+ * two or more tickers: fn CMP SPY,QQQ`).
+ */
+function tooFewTickersMessage(token: string, minimum: number, given: readonly string[], command: "fn" | "shot" = "fn"): string {
+  const example = [...given, ...EXAMPLE_TICKERS.filter((ticker) => !given.includes(ticker))].slice(0, Math.max(minimum, given.length + 1));
+  return `${token} needs ${COUNT_WORDS[minimum] ?? minimum} or more tickers: ${command} ${token} ${example.join(",")}`;
+}
+
+/** The tickers a function's argument lists, as its report reads them. */
+export function argumentSymbols(rawArgument: string): string[] {
+  return normalizeSymbolList(rawArgument);
+}
+
+export function validateSymbolCount(
   definition: HeadlessPaneDefinition,
   token: string,
   symbols: string[],
+  command: "fn" | "shot" = "fn",
 ): void {
   const minimum = definition.argument.minimum
     ?? (definition.argument.optional ? 0 : 1);
   const maximum = definition.argument.maximum;
   if (symbols.length < minimum) {
     if (minimum <= 1) throw requiredArgumentError(definition, token);
-    throw new Error(`${token} requires at least ${minimum} symbols.`);
+    throw new Error(tooFewTickersMessage(token, minimum, symbols, command));
   }
   if (maximum != null && symbols.length > maximum) {
     throw new Error(`${token} accepts at most ${maximum} symbols.`);
@@ -735,14 +754,14 @@ export function headlessReportTables(
       const rowsResult = result as HeadlessRowsResult;
       const columns = displayedColumns(columnsFor(rowsResult.rows, rowsResult.columns, definition.columns));
       const rowIdentities = rowIdentitiesOf(rowsResult.rows, rowsResult);
-      const own = exportRowsTable(title, columns, rowsResult.rows);
+      const own = exportRowsTable(title, columns, rowsResult.rows, { status: true });
       const interval = rowsResult.interval?.trim();
       tables = [{ ...own, ...(rowIdentities ? { rowIdentities } : {}), ...(interval ? { identity: { interval } } : {}) }, ...(rowsResult.exportTables ?? []).map((extra) => {
         const identity = {
           ...(extra.unit?.trim() ? { currencyOrUnit: extra.unit.trim() } : {}),
           ...(extra.interval?.trim() ? { interval: extra.interval.trim() } : {}),
         };
-        const table = exportRowsTable(extra.title, displayedColumns(extra.columns), extra.rows);
+        const table = exportRowsTable(extra.title, displayedColumns(extra.columns), extra.rows, { status: true });
         return Object.keys(identity).length > 0 ? { ...table, identity } : table;
       })];
       break;
@@ -758,7 +777,7 @@ export function headlessReportTables(
           const entries = exportEntriesTable(section.title, section.entries);
           return Object.keys(named).length > 0 ? { ...entries, identity: named } : entries;
         }
-        const table = exportRowsTable(section.title, displayedColumns(columnsFor(section.rows, section.columns, definition.columns)), section.rows);
+        const table = exportRowsTable(section.title, displayedColumns(columnsFor(section.rows, section.columns, definition.columns)), section.rows, { status: true });
         const identity = {
           ...named,
           ...(section.unit?.trim() ? { currencyOrUnit: section.unit.trim() } : {}),
@@ -776,7 +795,7 @@ export function headlessReportTables(
     }
     case "snapshot": {
       const snapshot = result as HeadlessSnapshotResult;
-      tables = [exportRowsTable(title, displayedColumns(columnsFor(snapshot.items, undefined, definition.columns)), snapshot.items)];
+      tables = [exportRowsTable(title, displayedColumns(columnsFor(snapshot.items, undefined, definition.columns)), snapshot.items, { status: true })];
       break;
     }
     default: {