gloomberb 0.18.4 → 0.19.0

package/src/cli/commands/search.ts

@@ -25,6 +25,7 @@ import { formatMarketPriceWithCurrency, quoteFormatOptions } from "../../market-
 import { formerIssuerLine, startTickerChangeLookup, type TickerChangeLookup } from "../../tickers/ticker-changes";
 import { fail, failRetryable } from "../errors";
 import { isProviderBusy, SEARCH_BUSY_CODE, SEARCH_BUSY_MESSAGE } from "../../sources/provider-errors";
+import { isNetworkFailure } from "../../utils/network-failure";
 import type { MarketContext } from "../types";
 import type { CliCommandContext, GloomPlugin } from "../../types/plugin";
 import { indexRootTryLine } from "../index-roots";
@@ -132,11 +133,13 @@ export async function searchCandidatesForCli({
     const quote = BARE_SYMBOL.test(symbol) && candidates.some((candidate) => candidate.symbol.toUpperCase() === symbol)
       ? await (quoted ?? loadSearchedQuote(symbol, savedExchange, dataProvider))
       : null;
-    return withQuotedNames(symbol, withHomeListingPrimary(trimmedQuery, withPrimaryListingFirst(symbol, candidates, quote)), quote)
+    return withQuotedNames(symbol, withUsLineOfPrimary(withHomeListingPrimary(trimmedQuery, withPrimaryListingFirst(symbol, candidates, quote))), quote)
       .slice(0, totalLimit);
   } catch (error) {
     // Not "No matches found": a script or a reader would take that for a name nothing lists.
     if (isProviderBusy(error)) failRetryable(SEARCH_BUSY_MESSAGE, SEARCH_BUSY_CODE);
+    // Nor is no answer at all: the command fails as "couldn't reach", as any command offline does.
+    if (isNetworkFailure(error)) throw error;
     logFailure("cli.commands-search", "Search ticker candidates failed")(error);
     return [];
   }
@@ -204,9 +207,19 @@ function formerIssuerNote(candidate: TickerSearchCandidate): string | null {
   return formerIssuerLine(former.symbol, former, former.successor ?? { symbol: candidate.label, name: resolveSearchName(candidate) });
 }
 
-/** The merged companies' lines, once each, unless the symbol's own line already says it. */
+/**
+ * A row search found by the name its company had before it was renamed
+ * ("cassava" finds Filana Therapeutics' FLNA): says what it was called.
+ */
+function formerNameNote(candidate: TickerSearchCandidate): string | null {
+  const formerName = candidate.result?.formerName;
+  if (typeof formerName !== "string" || !formerName.trim()) return null;
+  return `${candidate.label} is ${resolveSearchName(candidate)}, formerly ${formerName.trim()}`;
+}
+
+/** The merged companies' and renamed companies' lines, once each, unless the symbol's own line already says it. */
 function formerIssuerNotes(candidates: readonly TickerSearchCandidate[], fate: SearchFate): string[] {
-  const notes = new Set(candidates.flatMap((candidate) => formerIssuerNote(candidate) ?? []));
+  const notes = new Set(candidates.flatMap((candidate) => formerIssuerNote(candidate) ?? formerNameNote(candidate) ?? []));
   return [...notes].filter((note) => !fate.notes.some((line) => line.split(" ")[0] === note.split(" ")[0]));
 }
 
@@ -286,6 +299,26 @@ function withHomeListingPrimary(query: string, candidates: TickerSearchCandidate
   return [...rest.slice(0, at), { ...home, category: "Primary Listing" as const }, { ...primary, category: "Other Listings" as const }, ...rest.slice(at + 1)];
 }
 
+/**
+ * A company whose primary listing is abroad lists the US line of the same
+ * symbol right after it: the line `quote SHEL` reads (a bare symbol is its US
+ * listing), which a name search ("shell") would otherwise rank below the
+ * company's lines on other venues and cut. Any other list keeps its order.
+ */
+function withUsLineOfPrimary(candidates: TickerSearchCandidate[]): TickerSearchCandidate[] {
+  const primary = candidates.find((candidate) => candidate.category === "Primary Listing");
+  if (!primary || primary.kind !== "search" || isUsListingExchange(candidateExchange(primary))) return candidates;
+  const symbol = primary.symbol.toUpperCase();
+  const company = resolveSearchName(primary);
+  const us = candidates.find((candidate) => candidate !== primary && candidate.kind === "search" && !candidate.contractKey
+    && candidate.category !== "Funds & Derivatives" && candidate.symbol.toUpperCase() === symbol
+    && isUsListingExchange(candidateExchange(candidate)) && sameCompany(resolveSearchName(candidate), company));
+  if (!us) return candidates;
+  const rest = candidates.filter((candidate) => candidate !== us);
+  const at = rest.indexOf(primary) + 1;
+  return [...rest.slice(0, at), { ...us, category: "Other Listings" as const }, ...rest.slice(at)];
+}
+
 /** The candidate on the venue the quote prices; the US exchanges share one symbol, so a quote on any of them is its one US line. */
 function quotedCandidate(candidates: readonly TickerSearchCandidate[], quote: Quote | null): TickerSearchCandidate | undefined {
   const quoted = canonicalExchange(quote?.listingExchangeName || quote?.exchangeName);
@@ -366,6 +399,9 @@ function searchCandidateRows(candidates: TickerSearchCandidate[]) {
     saved: candidate.kind === "ticker",
     // The company that merged into this one, whose old name the query is.
     ...candidate.result?.formerIssuer ? { formerIssuer: candidate.result.formerIssuer } : {},
+    // The name a renamed company had, which the query is.
+    ...typeof candidate.result?.formerName === "string" && candidate.result.formerName.trim()
+      ? { formerName: candidate.result.formerName.trim() } : {},
   }));
 }
 

package/src/cli/commands/themes.ts

@@ -16,14 +16,23 @@ function themeChoicesText(): string {
   return `Themes: ${choices}. gloom config themes lists them with notes.`;
 }
 
+/** `Light themes: paper (Paper), github-light (GitHub Light), ...`, for `light` or `dark` typed as a theme; null for anything else. */
+function appearanceHint(input: string): string | null {
+  const appearance = input.trim().toLowerCase();
+  if (appearance !== "light" && appearance !== "dark") return null;
+  const matching = listThemes().filter((theme) => theme.appearance === appearance).map(({ id, name }) => `${id} (${name})`);
+  return matching.length > 0 ? ` ${appearance === "light" ? "Light" : "Dark"} themes: ${matching.join(", ")}.` : null;
+}
+
 /**
  * The id `input` names, by id or display name in any case. Anything else
- * fails with the closest id when there is one, and every id with its name.
+ * fails with the closest id when there is one, and every id with its name;
+ * `light` or `dark` with the themes of that look.
  */
 export function requireThemeId(input: string): string {
   const lookup = resolveThemeId(input);
   if (lookup.ok) return lookup.id;
-  const hint = lookup.suggestion ? ` Did you mean ${describeThemeId(lookup.suggestion)}?` : "";
+  const hint = appearanceHint(input) ?? (lookup.suggestion ? ` Did you mean ${describeThemeId(lookup.suggestion)}?` : "");
   return fail(`Unknown theme "${input.trim()}".${hint}`, themeChoicesText());
 }
 

package/src/cli/commands/ticker.ts

@@ -3,12 +3,12 @@ import { formatShortDate, parseDisplayDate } from "../../utils/datetime-format";
 import { formatReportedMoney } from "../../utils/reported-money";
 import {
   appTtmRate, computedEnterpriseValueNote, convertedPriceEarningsNote, enterpriseValueLabel, enterpriseValueReconciliationNote, epsConversionNote,
-  fundamentalsCurrency, reportedEnterpriseValue, ttmAtAppRate, ttmConversionNote,
+  fundamentalsCurrency, reportedEnterpriseValue, trailingEpsSourceNote, ttmAtAppRate, ttmConversionNote,
 } from "../../utils/fundamentals";
 import { latestFinancialPeriod } from "../../utils/latest-financial-period";
 import { burnsCash, cashRunway, SHORT_RUNWAY_HISTORY, formatRunwayMonths, offeringNote, offeringsAfter, runwayMethod, type CashRunway, type OfferingFiling, type RunwayEstimate } from "../../utils/cash-runway";
 import { exportedFundamentals, formatPriceEarnings, NOT_MEANINGFUL, priceEarningsOnEarnings } from "../../utils/price-earnings";
-import { describeFundamentalMarketCap, marketCapBasisNote, selectMarketCapitalization, viewMarketCapitalization } from "../../utils/market-capitalization";
+import { describeFundamentalMarketCap, marketCapBasisNote, selectMarketCapitalization, viewMarketCapitalization, withheldMarketCap } from "../../utils/market-capitalization";
 import {
   formatCompact,
   formatCurrency,
@@ -76,7 +76,7 @@ import { isKnownNonUsListing, secFilingItemCodes, US_FUND_FACTS_ONLY } from "../
 import { currentReportItemsLabel, hiddenFilingsNote, loadLatestFilings, type HiddenFilings } from "../../utils/sec-filings";
 import { canonicalExchange, exchangeLabel, isKnownExchangeCode, isUsListingExchange } from "../../utils/exchanges";
 import {
-  failIfNotTraded, failMovedSymbol, ListingArgError, listingChoiceNotes, listingFateLoader, listingIdentity, loadBareVenues,
+  coinListingNotes, failIfNotTraded, failMovedSymbol, ListingArgError, listingChoiceNotes, listingFateLoader, listingIdentity, loadBareVenues,
   resolveCliListing, type CliListing, type ListingDataRequest,
 } from "../listing-arg";
 import { movedAwayChange } from "../../tickers/ticker-changes";
@@ -92,12 +92,12 @@ import { fundamentalsFreshness, quotesFreshness } from "../freshness";
 import { distributionHistory, forwardDividendBasis, forwardDividendMayHaveLapsed, lapsedDividend, noCurrentDividend, TRAILING_DIVIDEND_BASIS, type DistributionHistory, type DividendLapse } from "../../utils/forward-dividend";
 import { declaredDividends } from "../../utils/declared-dividends";
 import { historyTrailingDividendYield, measuresTrailingYield } from "../../market-data/quotes/live-valuation";
-import { notTheCoinNote } from "./crypto-hints";
 import { loadOfferingFilings, loadStatementFilings, resultsReleaseText, statementPeriodText, type StatementFilingsReport } from "../statement-filings";
 import type { BankFiguresPayload } from "../../api-client/bank-figures";
 import { bankSection } from "../bank-section";
-import type { FundBondFacts } from "../../api-client/fund-facts";
-import { bondFigures, fetchFundBondFacts, NOT_SEC_YIELD } from "../../market-data/bond-funds";
+import type { FundBondFacts, FundFactsPayload } from "../../api-client/fund-facts";
+import { bondFigures, NOT_SEC_YIELD } from "../../market-data/bond-funds";
+import { readFundFacts } from "../../market-data/fund-facts";
 import { taxEquivalentLines, type TaxEquivalentAnalysis } from "../../market-data/tax-equivalent";
 import { isRoundTheClockCoin } from "../../utils/crypto-pair";
 import { coinNewsFallbackNotice } from "../../sources/gloomberb-cloud/news";
@@ -667,21 +667,23 @@ function isYieldMetric(label: string): boolean {
 }
 
 /**
- * A US-listed fund's bond facts for the yield lines; null for any other
- * listing, and when they cannot be read, which leaves the yield as it was.
+ * A US-listed fund's facts for the report: the bond figures its yield lines
+ * read, and whether `fn ETF` has figures to point to. Null for any other
+ * listing, and when they cannot be read, which leaves the yield as it was
+ * and points nowhere.
  */
-export async function loadReportBondFacts(
+export async function loadReportFundFacts(
   symbol: string,
   exchange: string | undefined,
   financials: Pick<TickerFinancials, "quote" | "quoteMetadata">,
   tickerFile: TickerRecord | null = null,
-  load: (symbol: string) => Promise<FundBondFacts | null> = fetchFundBondFacts,
-): Promise<FundBondFacts | null> {
+  load: (symbol: string) => Promise<FundFactsPayload> = (ticker) => readFundFacts(ticker),
+): Promise<FundFactsPayload | null> {
   if (resolveTickerInstrumentKind(tickerFile, financials) !== "fund" || (exchange && !isUsListingExchange(exchange))) return null;
   try {
     return await load(symbol);
   } catch (error) {
-    logFailure("cli.commands-ticker", "Read bond fund facts failed")(error);
+    logFailure("cli.commands-ticker", "Read fund facts failed")(error);
     return null;
   }
 }
@@ -712,7 +714,8 @@ function fundamentalsMetrics(
     { label: "P/E (TTM)", ...multipleFigure(priceEarningsOnEarnings(fundamentals?.trailingPE, fundamentals?.eps)) },
     { label: "Forward P/E", ...multipleFigure(priceEarningsOnEarnings(fundamentals?.forwardPE, fundamentals?.forwardEps)) },
     { label: "PEG", ...multipleFigure(fundamentals?.pegRatio) },
-    // The flows and EPS are one trailing-twelve-month block, the same twelve months for each line.
+    // EPS (TTM) is the last four filed quarters' (filed-trailing-eps), so its twelve months can end before those of
+    // the flows below, Gloom Cloud's trailing block; Gloom Cloud's EPS standing in is noted (trailingEpsSourceNote).
     { label: "EPS (TTM)", ...reportedMoney(fundamentals?.eps, fundamentals?.epsCurrency?.trim() || reportingCurrency, true, codes) },
     {
       label: dividendYieldLabel(fundamentals?.dividendYieldBasis, bond),
@@ -797,6 +800,7 @@ function fundamentalsNotes(
     : undefined;
   const conversion = [...TRAILING_MONEY_METRICS].some(shown) ? ttmConversionNote(fundamentals) : undefined;
   const eps = shown("EPS (TTM)") ? epsConversionNote(fundamentals) : undefined;
+  const epsSource = trailingEpsSourceNote(fundamentals, { eps: shown("EPS (TTM)"), pe: shown("P/E (TTM)") });
   const priceEarnings = metrics.some((metric) => metric.label === "P/E (TTM)" && typeof metric.value === "number")
     ? convertedPriceEarningsNote(fundamentals, quoteCurrency)
     : undefined;
@@ -804,7 +808,9 @@ function fundamentalsNotes(
   const enterpriseValue = shown("Enterprise Value")
     ? enterpriseValueReconciliationNote(fundamentals) ?? computedEnterpriseValueNote(fundamentals)
     : undefined;
-  return [shareBasis, enterpriseValue, conversion, eps, priceEarnings].filter((note): note is string => !!note);
+  // A cap Gloom Cloud withheld says why, as RV and EQS do.
+  const withheld = withheldMarketCap(fundamentals)?.note;
+  return [withheld, shareBasis, enterpriseValue, conversion, eps, epsSource, priceEarnings].filter((note): note is string => !!note);
 }
 
 // The share count is the market cap's basis: the cap is the count times the price, or a note says why not.
@@ -814,8 +820,10 @@ type FundamentalsReportData = TickerFinancials & {
   symbol: string;
   exchange?: string;
   distributions?: DividendDistributions | null;
-  /** A bond fund's SEC yield, yield to worst and duration (loadReportBondFacts). */
+  /** A bond fund's SEC yield, yield to worst and duration (loadReportFundFacts). */
   bondFund?: FundBondFacts | null;
+  /** A US-listed fund's facts (loadReportFundFacts): the note points to `fn ETF` only when they cover it. */
+  fundFacts?: FundFactsPayload | null;
   /** `fundamentals --tax-rate`: the tax-equivalent yield and muni/Treasury ratio. */
   taxEquivalent?: TaxEquivalentAnalysis | null;
   /** The filings behind the latest statements, and a newer quarter's results release. */
@@ -839,20 +847,25 @@ function statementFilingsNotes(report: StatementFilingsReport | null | undefined
 }
 
 /**
- * Where a fund's facts are: for a US listing, the ETF function (fee, NAV,
- * premium, net assets); a fund listed elsewhere has none yet. Only for a
- * fund: a stock's report says nothing of it.
+ * Where a fund's facts are: for a US listing, the ETF function, naming the
+ * figures it has (fee, NAV, premium, net assets), and only when it has some:
+ * a fund it has none for, or whose facts could not be read, gets no pointer
+ * to a pane that would only say why. A fund listed elsewhere has none yet.
+ * Only for a fund: a stock's report says nothing of it.
  */
 function fundFactsNote(
   symbol: string,
   exchange: string | undefined,
   financials: Pick<TickerFinancials, "quote" | "quoteMetadata">,
   tickerFile: TickerRecord | null = null,
+  facts: FundFactsPayload | null = null,
 ): string | null {
   if (resolveTickerInstrumentKind(tickerFile, financials) !== "fund") return null;
-  return !exchange || isUsListingExchange(exchange)
-    ? `Fund facts (fee, NAV, premium, net assets): fn ETF ${symbol}.`
-    : US_FUND_FACTS_ONLY;
+  if (exchange && !isUsListingExchange(exchange)) return US_FUND_FACTS_ONLY;
+  if (!facts?.covered) return null;
+  const figures = [facts.expenseRatio && "fee", facts.nav && "NAV", facts.premiumDiscount && "premium", facts.netAssets && "net assets"]
+    .filter((figure): figure is string => !!figure);
+  return `Fund facts${figures.length ? ` (${figures.join(", ")})` : ""}: fn ETF ${symbol}.`;
 }
 
 /**
@@ -947,7 +960,7 @@ export function renderFundamentalsReport(
   const before = lines.length;
   const metrics = fundamentalsReportMetrics(financials, view);
   appendMetricSection(lines, view === "valuation" ? "Valuation" : "Fundamentals", metricLines(metrics));
-  const fund = fundFactsNote(symbol, financials.exchange || quote?.exchangeName, financials);
+  const fund = fundFactsNote(symbol, financials.exchange || quote?.exchangeName, financials, null, financials.fundFacts);
   if (lines.length === before) lines.push("", cliStyles.muted([`No ${view} reported for ${financials.symbol}.`, fund].filter(Boolean).join(" ")));
   else if (fund) lines.push(cliStyles.muted(fund));
   for (const note of fundamentalsNotes(atRegularSessionPrice(financials), metrics, quote?.currency)) lines.push(cliStyles.muted(note));
@@ -987,7 +1000,8 @@ export function fundamentalsReportTables(
   freshness: ReportFreshness,
 ): CliReportTables {
   const metrics = fundamentalsReportMetrics(financials, view);
-  const fund = fundFactsNote(financials.quote?.symbol ?? financials.symbol, financials.exchange || financials.quote?.exchangeName, financials);
+  const fund = fundFactsNote(financials.quote?.symbol ?? financials.symbol, financials.exchange || financials.quote?.exchangeName, financials, null,
+    financials.fundFacts);
   const tables = [exportEntriesTable(
     view === "valuation" ? "Valuation" : "Fundamentals",
     metrics.map((metric) => ({ label: metric.label, value: metric.value, formatted: metric.text, unit: metric.unit })),
@@ -1064,6 +1078,7 @@ export async function buildTickerReport({
   distributions = null,
   statementFilings = null,
   bondFund = null,
+  fundFacts = null,
   memberships,
   offerings = [],
 }: {
@@ -1074,8 +1089,10 @@ export async function buildTickerReport({
   statementFilings?: StatementFilingsReport | null;
   /** The company's latest offering prospectuses (424B5, 424B4); those after the latest balance sheet get a note. */
   offerings?: readonly OfferingFiling[];
-  /** A bond fund's SEC yield, yield to worst and duration (loadReportBondFacts). */
+  /** A bond fund's SEC yield, yield to worst and duration (loadReportFundFacts). */
   bondFund?: FundBondFacts | null;
+  /** A US-listed fund's facts (loadReportFundFacts): the report points to `fn ETF` only when they cover it. */
+  fundFacts?: FundFactsPayload | null;
   /** The distributions a dividend yield is read with (loadDividendDistributions). */
   distributions?: DividendDistributions | null;
   /** The exchange the command named, as a canonical code. */
@@ -1091,7 +1108,7 @@ export async function buildTickerReport({
   notes?: string;
   /** Why there is no quote, when a source said; "Quote unavailable." otherwise. */
   quoteNote?: string;
-  /** "CAR = Avis Budget Group, NASDAQ (also XETRA, ASX)", for a bare symbol several companies list. */
+  /** "CAR = Avis Budget Group, NASDAQ (different companies on XETRA, ASX)", for a bare symbol several companies list. */
   listingNote?: string;
   recentNews?: NewsArticle[];
   recentSecFilings?: SecFilingItem[];
@@ -1254,7 +1271,8 @@ export async function buildTickerReport({
   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);
+    quote?.tradingExchangeName || listingExchange || quote?.listingExchangeName || quote?.exchangeName || tickerFile?.metadata.exchange, financials, tickerFile,
+    fundFacts);
   if (fund) lines.push(...lines.length === beforeFundamentals ? [""] : [], cliStyles.muted(fund));
 
   if (capitalization?.provenance.kind === "fundamentals") {
@@ -1494,7 +1512,8 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
 
     let financials: TickerFinancials | null = null;
     try {
-      financials = await dataProvider.getTickerFinancials(requestSymbol, exchange);
+      // The Change line says what the move is from.
+      financials = await dataProvider.getTickerFinancials(requestSymbol, exchange, { datesChangeBasis: true });
     } catch (error) {
       // A known exchange the symbol is not listed on: say where it is.
       await failIfNotTraded(listing, { store, dataProvider }, { fail: failCommand });
@@ -1534,10 +1553,11 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
     // The yield's distributions, read beside the rest when a trailing yield, a forward basis or its lapse needs them; they never fail the report.
     const distributions = loadDividendDistributions(dataProvider, { symbol: requestSymbol, exchange }, resolvedFinancials,
       { declared: !dependencies.printResult });
-    // A bond fund's SEC yield, yield to worst and duration, beside its distribution yield.
-    const bondFund = loadReportBondFacts(requestSymbol,
+    // A fund's facts: its bond figures beside its distribution yield, and whether fn ETF has any to point to.
+    const fundFacts = loadReportFundFacts(requestSymbol,
       quote?.tradingExchangeName || exchange || quote?.listingExchangeName || quote?.exchangeName || tickerFile?.metadata.exchange,
       resolvedFinancials, tickerFile);
+    const bondFund = fundFacts.then((facts) => facts?.bond ?? null);
     const statementFilings = loadStatementFilings(statementSources, { symbol: requestSymbol, exchange }, {
       quarter: latestFinancialPeriod(resolvedFinancials.quarterlyStatements, (row) => row.date),
       annual: latestFinancialPeriod(resolvedFinancials.annualStatements, (row) => row.date),
@@ -1588,17 +1608,18 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
     // The quote is the feed in this report; without one, the fundamentals date it.
     const freshness = quote ? quotesFreshness([quote]) : fundamentalsFreshness(resolvedFinancials);
     const quoteNote = quote ? undefined : await quoteUnavailableNote(dataProvider, requestSymbol, exchange);
-    const [choiceNote] = await listingChoiceNotes(listing, { store, dataProvider }, quote, venues);
-    // A bare coin ticker read as a fund says where the coin is, as `quote` does; a named listing was meant.
-    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;
+    // A bare coin ticker read as another listing says where the coin is, as `quote` does: from the quote, else from the saved listing.
+    const choiceNotes = [
+      ...await listingChoiceNotes(listing, { store, dataProvider }, quote, venues),
+      ...quote || !tickerFile ? [] : coinListingNotes(listing, { name: tickerFile.metadata.name, instrumentType: tickerFile.metadata.assetCategory }),
+    ];
+    const listingNote = choiceNotes.join("\n") || undefined;
     const memberships = await membershipsLoad;
     // A converted TTM block at the rate the rest of the report converts at, the one `fx` reports.
     const shownFinancials = await atReportTtmRate(resolvedFinancials, toBase);
     if (dependencies.printResult) {
       const newsNote = recentNews[0]?.searchedFor ? coinNewsFallbackNotice(requestSymbol, recentNews[0].searchedFor) : null;
-      const warnings = [choiceNote, coinNote, quoteNote, newsNote].filter((note): note is string => !!note);
+      const warnings = [...choiceNotes, quoteNote, newsNote].filter((note): note is string => !!note);
       dependencies.printResult({
         freshness,
         warnings: warnings.length > 0 ? warnings : undefined,
@@ -1642,6 +1663,7 @@ export async function ticker(symbol: string, dependencies: TickerCommandDependen
         distributions: await distributions,
         statementFilings: await statementFilings,
         bondFund: await bondFund,
+        fundFacts: await fundFacts,
         memberships,
         offerings: await offerings,
     }));

package/src/cli/company-name-hint.ts

@@ -0,0 +1,41 @@
+import type { CliListing } from "./listing-arg";
+import { companyNameSuggestion, isUnsettledNoProvider, type ListingDeps } from "./listing-arg";
+import { describeSuggestion } from "./listing-suggestion";
+import { isNotATickerMessage, withListingSuggestion } from "./not-a-ticker";
+
+type SearchDeps = Pick<ListingDeps, "dataProvider">;
+
+/**
+ * "Not a ticker: PALANTIR TECHNOLOGIES. Did you mean PLTR (Palantir
+ * Technologies Inc.)?" for words typed where one ticker goes, with the
+ * company search names for them. Without one the sentence ends at the
+ * symbol, and the error printer adds the search to try.
+ */
+export async function notATickerWords(typed: string, deps: SearchDeps): Promise<string> {
+  const symbol = typed.trim().replace(/^\$/, "").toUpperCase();
+  const message = `Not a ticker: ${symbol}.`;
+  const suggestion = await companyNameSuggestion(typed, deps);
+  return suggestion ? withListingSuggestion(message, describeSuggestion(suggestion)) : message;
+}
+
+/**
+ * Why a command stops on a listing whose own quote failed with `error`, when
+ * the word typed for it is no ticker, or null when it is not known to be: the
+ * source's "Not a ticker: PALANTIR.", and a word a source could not answer for
+ * (a timeout, a rate limit) that search resolves to a company all the same, as
+ * `quote` says it of a name. Both name the company beside it. A real ticker a
+ * source failed to quote is not stopped here: it is not a company's name.
+ */
+export async function notATickerStop(
+  error: unknown,
+  listing: Pick<CliListing, "symbol" | "exchange" | "typed">,
+  deps: SearchDeps,
+): Promise<string | null> {
+  const message = error instanceof Error ? error.message : null;
+  const notATicker = isNotATickerMessage(message);
+  if (!notATicker && !isUnsettledNoProvider(error)) return null;
+  if (listing.exchange || !listing.typed) return notATicker ? message : null;
+  const suggestion = await companyNameSuggestion(listing.typed, deps);
+  if (!suggestion) return notATicker ? message : null;
+  return withListingSuggestion(notATicker ? message! : `Not a ticker: ${listing.symbol}.`, describeSuggestion(suggestion));
+}

package/src/cli/earnings-calendar.ts

@@ -43,7 +43,7 @@ export async function noListingCalendarNote(
 }
 
 /**
- * "SAN = Banco Santander, NYSE (also EPA, LSE)" for a bare symbol whose
+ * "SAN = Banco Santander, NYSE (different companies on EPA, LSE)" for a bare symbol whose
  * calendar date is its US line's, when several companies list the symbol:
  * the event names the company the date is for.
  */

package/src/cli/errors.ts

@@ -9,9 +9,11 @@ import { DATA_SERVICE_UNREACHABLE_MESSAGE, isNetworkFailure } from "../utils/net
 
 const USAGE_PREFIX = "Usage: ";
 /** The code of every error a command fails with: bad input, nothing found, an option it does not take. */
-const CLI_ERROR_CODE = "cli_error";
+export const CLI_ERROR_CODE = "cli_error";
+/** The code of a command that ran, and the data service has nothing for what it asked. */
+export const NO_DATA_CODE = "no_data";
 /** The code of a command whose requests never reached the data service. */
-const SERVICE_UNREACHABLE_CODE = "service_unreachable";
+export const SERVICE_UNREACHABLE_CODE = "service_unreachable";
 
 /** What to check when nothing answered: the connection, and the proxy when one is set. */
 function unreachableHint(): string {
@@ -61,6 +63,12 @@ export function failWithFields(message: string, code: string, fields: Record<str
   throw new CliFailure(message, undefined, code, undefined, fields);
 }
 
+/** Fails as `error` says: its code, message, details and whether to retry, and any field it carries beside them. */
+export function failWithError(error: CliErrorObject): never {
+  const { code, message, details, retryable, ...fields } = error;
+  throw new CliFailure(message, details, code, retryable, Object.keys(fields).length > 0 ? fields : undefined);
+}
+
 /** Fails with what asking again shortly may get past (a busy service): `--json` marks it `retryable`. */
 export function failRetryable(message: string, code: string): never {
   throw new CliFailure(message, undefined, code, true);

package/src/cli/export-source.ts

@@ -3,7 +3,8 @@
  * writes CSV or JSON, so an export can go in an audit file as it is: CSV ends
  * with `#` lines and JSON carries a `source` object with the same fields.
  * CSV and NDJSON rows also end with five fixed columns naming what each row
- * is (`EXPORT_IDENTITY_COLUMNS`), less any the table already has by name.
+ * is (`EXPORT_IDENTITY_COLUMNS`), less any the table already has by name; a
+ * dated export adds `period`, `released` and `retrieved` after them.
  */
 import { formatFreshnessLine, type ReportFreshness } from "./pane-functions/freshness";
 import { parseReportTime } from "../utils/utc-time";
@@ -54,6 +55,14 @@ export function exportSource(freshness: ReportFreshness): ExportSource {
  */
 export const EXPORT_IDENTITY_COLUMNS = ["symbol_or_series", "currency_or_unit", "interval", "source", "as_of"] as const;
 
+/**
+ * The columns a dated export (`econ`, `fred`, `fn ECST`) ends with after the
+ * five: the period a figure covers, when it was released, and when this export
+ * retrieved it. `as_of` is then the release, and these three say the rest, so a
+ * row never has to be read against the closing lines to be dated.
+ */
+export const EXPORT_DATING_COLUMNS = ["period", "released", "retrieved"] as const;
+
 /** What a command knows about the rows it exports; source and as-of come from its freshness. */
 export interface ExportIdentity {
   /** The symbol or series ID asked for: `USDZAR=X`, `SAN:EPA`, `DEXSFUS`. */
@@ -68,6 +77,10 @@ export interface ExportIdentity {
    * blank; absent, it is the closing lines' observation date.
    */
   asOf?: string | null;
+  /** In a dated export: the period the figure covers, as its publisher names it (`Sep 2026`, `2026-09-01`). */
+  period?: string | null;
+  /** In a dated export: when the figure was released, an ISO date or instant; null when the data does not say. */
+  released?: string | null;
 }
 
 /** A row's own as-of in the closing lines' form: a date stays a date, an instant is ISO in UTC. */
@@ -94,6 +107,21 @@ export function exportIdentityCells(freshness: ReportFreshness, identity: Export
   ];
 }
 
+/**
+ * The cells of `EXPORT_DATING_COLUMNS` for a row: its period and release as
+ * the data states them, blank when it does not, and the time this export
+ * retrieved the data.
+ */
+export function exportDatingCells(freshness: ReportFreshness, identity: ExportIdentity = {}): string[] {
+  return [identity.period?.trim() ?? "", rowAsOf(identity.released ?? null), exportSource(freshness).retrievalTime];
+}
+
+/** The three dating fields of an NDJSON row, null where blank. */
+export function exportDatingFields(freshness: ReportFreshness, identity: ExportIdentity = {}): Record<string, string | null> {
+  const cells = exportDatingCells(freshness, identity);
+  return Object.fromEntries(EXPORT_DATING_COLUMNS.map((column, index) => [column, cells[index] || null]));
+}
+
 /** The same five as fields of an NDJSON row, null where blank. */
 export function exportIdentityFields(freshness: ReportFreshness, identity: ExportIdentity = {}): Record<string, string | null> {
   const cells = exportIdentityCells(freshness, identity);

package/src/cli/glossary.ts

@@ -714,7 +714,30 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
   },
   {
     term: "Other reportables", aliases: ["other reportable", "other reportable traders"], functions: ["COT"], shown: ["Other Reportables"],
-    definition: "The disaggregated report's large traders that fit none of its other classes, such as proprietary traders and family offices.",
+    definition: "The disaggregated and TFF reports' large traders that fit none of their other classes, such as proprietary traders and family offices.",
+  },
+  // The Traders in Financial Futures report's classes, and the options it can count.
+  {
+    term: "Traders in Financial Futures", short: "TFF", aliases: ["tff report", "financial futures report", "financial traders report"], functions: ["COT"], shown: ["Financial (TFF)"],
+    definition: "The CFTC's report on financial futures, such as rates, currencies, stock indexes and VIX. "
+      + "It splits large traders into dealers, asset managers, leveraged funds and other reportables.",
+  },
+  {
+    term: "Leveraged funds", aliases: ["leveraged fund", "leveraged money", "lev funds"], functions: ["COT"], shown: ["Leveraged Funds"],
+    definition: "The TFF report's hedge funds, CTAs and other money managers trading for clients or with borrowed money: the speculators most watched in rates, currencies and indexes.",
+  },
+  {
+    term: "Asset manager/institutional", aliases: ["asset manager", "asset managers", "institutional", "real money"], functions: ["COT"], shown: ["Asset Manager/Institutional"],
+    definition: "The TFF report's pension funds, insurers, mutual funds and endowments, investing for the long run; usually net long stock index futures.",
+  },
+  {
+    term: "Dealer/intermediary", aliases: ["dealer intermediary", "intermediary", "intermediaries"], functions: ["COT"], shown: ["Dealer/Intermediary"],
+    definition: "The TFF report's banks and dealers on the sell side, taking the other side of their clients' trades and hedging it.",
+  },
+  {
+    term: "Futures and options combined", aliases: ["futures + options", "futures and options", "combined report", "combined positions"], functions: ["COT"], shown: ["Futures + options"],
+    definition: "A COT report that adds each group's options to its futures, delta-adjusted: an option counts as the futures it moves like. "
+      + "Futures only, the default, counts futures alone.",
   },
   // Futures basis and curve shape (CTM, FUT, PERP).
   {
@@ -778,6 +801,42 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
     definition: "Cboe's index of the 30-day volatility that VIX options price: the VIX of the VIX. A high reading means traders are paying up "
       + "to protect against sudden jumps in VIX itself.",
   },
+  // Options positioning (OPX, GEX) and the volatility surface (OVDV).
+  {
+    term: "Max pain", aliases: ["max-pain", "maximum pain", "max pain strike", "pain strike"], functions: ["OPX", "GEX"],
+    definition: "The settlement price at which one expiry's options would pay their holders the least, summed over every call's and put's open interest: "
+      + "the strike where Payout $ is lowest. It says where option holders collect least at expiry, not where the price will go. "
+      + "Deribit's BTC and ETH options settle at 08:00 UTC on the day named, against its index averaged over the 30 minutes before.",
+  },
+  {
+    term: "Payout $", aliases: ["payout", "expiry payout", "option payout", "payout at expiry"], functions: ["OPX", "GEX"], shown: ["Payout $"],
+    definition: "What an expiry's options would pay their holders, in dollars, if the underlying settled at that strike: each call's open interest times "
+      + "how far the strike is above the call's, plus each put's times how far it is below, times the contract size (100 shares for a US listing, "
+      + "1 BTC or 1 ETH on Deribit). Max pain is the strike where it is lowest.",
+  },
+  {
+    term: "Call wall", aliases: ["put wall", "walls", "gamma wall", "gamma walls"], functions: ["OPX", "GEX"], shown: ["Call wall", "Put wall"],
+    definition: "The strike with the most dealer gamma from calls (call wall) or from puts (put wall), across every expiry or within one. "
+      + "Hedging flows are largest there, so it is often read as resistance above spot and support below it.",
+  },
+  {
+    term: "Risk reversal", short: "RR", aliases: ["25d risk reversal", "25-delta risk reversal", "25 delta risk reversal", "rr25", "risk reversals"],
+    functions: ["OVDV"], shown: ["RR"],
+    definition: "The 25-delta call's implied volatility minus the 25-delta put's, in vol points, for one expiry. Negative means puts cost more than calls "
+      + "as far from the forward (downside protection is bid), positive that upside calls are. OVDV, VCA and HIVG's rr25d all sign it call minus put.",
+  },
+  {
+    term: "Butterfly", short: "BF", aliases: ["25d butterfly", "25-delta butterfly", "25 delta butterfly", "bf25", "smile curvature", "fly"],
+    functions: ["OVDV"], shown: ["BF"],
+    definition: "The average of the 25-delta call and put implied volatilities minus the implied volatility at the forward, in vol points, for one expiry: "
+      + "how much the wings cost over the middle of the smile. A higher butterfly prices larger moves in either direction.",
+  },
+  {
+    term: "DVOL", aliases: ["deribit volatility index", "bitcoin volatility index", "ether volatility index", "btc dvol", "eth dvol", "crypto vix"],
+    functions: ["OVDV", "G"], shown: ["DVOL"],
+    definition: "Deribit's volatility index for BTC or ETH: the 30-day implied volatility its options price, in vol points, computed from the whole "
+      + "strip of strikes as VIX is. OVDV shows it beside the coin's surface; chart it as CAP:volatility:dvol-btc or CAP:volatility:dvol-eth.",
+  },
   // The economic calendar (ECO).
   {
     term: "Actual", aliases: ["actual release", "actual value"], functions: ["ECO"], shown: ["ACTUAL", "Actual"],
@@ -795,6 +854,19 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
     term: "Impact", short: "IMP", aliases: ["importance", "event impact", "high impact"], functions: ["ECO"],
     definition: "How much a release usually moves markets: HIGH for the big ones (CPI, jobs, rate decisions), MED and LOW for speeches and smaller data.",
   },
+  {
+    term: "Purchasing managers' index", short: "PMI", aliases: ["pmis", "purchasing managers", "purchasing managers index", "ism", "ism pmi",
+      "flash pmi", "caixin pmi", "ratingdog pmi"], functions: ["ECO"],
+    definition: "A monthly survey of companies' purchasing managers on orders, output, jobs and prices: 50 is no change from the month before, "
+      + "above it growth, below it contraction. A flash PMI is the month's early read, the final a week or so later. ECO lists each as a release: "
+      + "ISM for the US, S&P Global's elsewhere, NBS and RatingDog (formerly Caixin) for China, most at medium or low impact.",
+  },
+  // Economic statistics (ECST).
+  {
+    term: "Nowcast", aliases: ["nowcasts", "nowcasting", "gdpnow", "gdp nowcast"], functions: ["ECST", "ECO"], shown: ["GDPNow"],
+    definition: "An estimate of this quarter's GDP growth from the data already out, revised as each release lands until the official figure. "
+      + "ECST shows the Atlanta Fed's GDPNow, annualized, against its own history; ECO lists each update as a release.",
+  },
 ];
 
 const ANSI = /\x1b\[[0-9;]*m/g;