gloomberb 0.16.4 → 0.16.5

package/src/cli/glossary.ts

@@ -0,0 +1,429 @@
+import { cliStyles, cliTerminalWidth, renderDefinitions, renderSection, wrapText } from "../utils/cli-output";
+
+/**
+ * Plain-words meanings of the rates, auction, energy and perpetual-futures terms the
+ * functions show in their rows, headers and footers. `catalog glossary` lists them,
+ * `catalog explain <term>` prints one and `fn <function> --explain` follows a
+ * report with the ones it shows. Only terms a pane or report actually prints
+ * belong here.
+ */
+export interface GlossaryEntry {
+  term: string;
+  /** The abbreviation a table heads the column with, printed beside the term: `B/C`. */
+  short?: string;
+  /** Other names a reader may look it up by: `stop-out` for the high yield. */
+  aliases: readonly string[];
+  /** The functions that show it, by the token `fn` takes. */
+  functions: readonly string[];
+  /**
+   * The labels a report prints when it shows the term, matched whole and
+   * case-sensitively by `--explain`; the term and its abbreviation by default.
+   * A row type can stand for it: an AUCT Note row's rate is a high yield.
+   */
+  shown?: readonly string[];
+  /** One or two plain sentences. */
+  definition: string;
+}
+
+export const GLOSSARY: readonly GlossaryEntry[] = [
+  // Treasury auctions (AUCT).
+  {
+    term: "Bid-to-cover", short: "B/C", aliases: ["btc", "cover ratio"], functions: ["AUCT"],
+    definition: "Dollars bid for every dollar of securities the Treasury sold. A higher ratio means more demand.",
+  },
+  {
+    term: "Indirect", aliases: ["indirect bidders", "indirect bid", "indirect share"], functions: ["AUCT"],
+    definition: "The share of the competitive award won by indirect bidders, who bid through a dealer or broker. "
+      + "They include foreign central banks, so a high share reads as strong outside demand.",
+  },
+  {
+    term: "Direct", aliases: ["direct bidders", "direct bid", "direct share"], functions: ["AUCT"],
+    definition: "The share of the competitive award won by direct bidders, who bid for their own account straight to the Treasury.",
+  },
+  {
+    term: "Dealer", aliases: ["primary dealer", "primary dealers", "dealers", "dealer share", "dealer takedown", "takedown"],
+    functions: ["AUCT"], shown: ["Dealer", "Primary dealer"],
+    definition: "The share of the competitive award left to the primary dealers, the banks that must bid at every auction. "
+      + "Indirect, direct and dealer add up to 100%, so a high dealer share reads as weak demand.",
+  },
+  {
+    term: "Competitive", aliases: ["competitive bids", "noncompetitive"], functions: ["AUCT"],
+    definition: "Bids that name the yield the bidder will accept; they set the auction result. Noncompetitive bids take whatever that result is.",
+  },
+  {
+    term: "High yield", aliases: ["stop-out", "stop-out yield", "stop-out rate", "high rate"], functions: ["AUCT"],
+    shown: ["High yield", "Note", "Bond", "TIPS"],
+    definition: "The highest yield the Treasury accepted at a note, bond or TIPS auction, also called the stop-out yield. "
+      + "Every winning bid is filled at it; for TIPS it is a real yield.",
+  },
+  {
+    term: "Stop-out vs average", aliases: ["stop-out vs avg", "vs avg", "stop-out vs median"], functions: ["AUCT"],
+    shown: ["Stop-out vs avg", "Stop-out vs average"],
+    definition: "The high (stop-out) yield minus the auction's average/median yield, in basis points; bills compare discount rates. "
+      + "A wider gap means the last accepted bids cleared well above where most of the auction priced.",
+  },
+  {
+    term: "Tail", aliases: ["tailed", "tailing", "auction tail"], functions: ["AUCT"], shown: ["tail"],
+    definition: "How far an auction's high yield cleared above the when-issued yield at the 1 pm bid deadline; a tail reads as weak demand. "
+      + "AUCT cannot show one, as its source has no when-issued yields, so it shows stop-out vs average instead.",
+  },
+  {
+    term: "When-issued", short: "WI", aliases: ["when issued", "wi yield", "when-issued yield"], functions: ["AUCT"],
+    shown: ["when-issued", "When-issued"],
+    definition: "Trading in a Treasury security between its announcement and its issue. The when-issued yield at the auction deadline is what a tail is measured against.",
+  },
+  {
+    term: "Investment rate", aliases: ["bill rate", "coupon equivalent", "bond-equivalent yield"], functions: ["AUCT"],
+    shown: ["Investment rate", "Bill", "CMB"],
+    definition: "A bill's yield at the highest accepted (stop-out) rate, restated as a bond-equivalent yield so it compares with "
+      + "note yields. It reads higher than the bill's discount rate.",
+  },
+  {
+    term: "High discount margin", aliases: ["discount margin", "frn margin"], functions: ["AUCT"],
+    shown: ["High discount margin", "FRN"],
+    definition: "For a floating rate note, the highest spread over the 13-week bill rate the Treasury accepted, in basis points.",
+  },
+  {
+    term: "Median yield", aliases: ["avg/median yield", "average/median yield", "average yield"], functions: ["AUCT"],
+    definition: "Half the accepted competitive bids were at or below this yield. Close to the high yield means the bids were tightly bunched.",
+  },
+  {
+    term: "Term", aliases: ["reopening", "reopened", "security term"], functions: ["AUCT"],
+    definition: "How long the security runs from issue to maturity. A reopening sells more of an older issue, so its term "
+      + "reads short of a round number: 29-Year 10-Month is a reopened 30-year bond.",
+  },
+  {
+    term: "CUSIP", aliases: ["cusip number"], functions: ["AUCT"],
+    definition: "The nine-character code that identifies a US security. A reopening repeats the original issue's CUSIP.",
+  },
+  {
+    term: "Bill", aliases: ["t-bill", "treasury bill", "bills"], functions: ["AUCT", "BTMM"], shown: ["Bill", "bill"],
+    definition: "Treasury debt of a year or less, sold below face value with no coupon; the climb back to face value is the interest.",
+  },
+  {
+    term: "Note", aliases: ["treasury note", "notes"], functions: ["AUCT"],
+    definition: "Treasury debt that runs 2 to 10 years and pays a fixed coupon every six months.",
+  },
+  {
+    term: "Bond", aliases: ["treasury bond", "bonds", "long bond"], functions: ["AUCT"],
+    definition: "Treasury debt that runs 20 or 30 years and pays a fixed coupon every six months.",
+  },
+  {
+    term: "TIPS", aliases: ["treasury inflation-protected securities", "inflation-protected", "linkers"], functions: ["AUCT", "GC"],
+    definition: "Treasury Inflation-Protected Securities. Their principal follows US consumer prices, so their yield is a real yield, after inflation.",
+  },
+  {
+    term: "FRN", aliases: ["floating rate note", "floater"], functions: ["AUCT"],
+    definition: "A two-year Treasury floating rate note: it pays the 13-week bill rate, reset every week, plus a spread fixed when it is first sold.",
+  },
+  {
+    term: "CMB", aliases: ["cash management bill"], functions: ["AUCT"],
+    definition: "Cash management bill: an off-schedule bill the Treasury sells to cover a short-term cash need.",
+  },
+  // Yield curves (GC).
+  {
+    term: "Basis point", short: "bp", aliases: ["bps", "basis points"], functions: ["GC", "AUCT", "BTMM", "WIRP"],
+    definition: "One hundredth of a percentage point. A yield going from 4.00% to 4.25% has risen 25bp.",
+  },
+  {
+    term: "2s10s", aliases: ["2s10s spread", "twos tens", "curve slope", "inversion", "inverted curve"], functions: ["GC"],
+    definition: "The 10-year yield minus the 2-year yield, in basis points. Below zero the curve is inverted: short-term debt pays more than long-term.",
+  },
+  {
+    term: "UST", aliases: ["treasury curve", "us treasury curve", "par yield", "par curve"], functions: ["GC"],
+    definition: "The US Treasury par yield curve: for each maturity, the coupon a Treasury priced at face value would pay.",
+  },
+  {
+    term: "Real yield", aliases: ["tips real", "real rate"], functions: ["GC"], shown: ["Real yield", "TIPS real"],
+    definition: "A yield after inflation, read from TIPS prices.",
+  },
+  {
+    term: "Breakeven", aliases: ["breakeven inflation", "breakevens", "bei"], functions: ["GC"],
+    definition: "The nominal Treasury yield minus the TIPS real yield at the same maturity: the inflation rate at which both pay the same. "
+      + "It carries risk and liquidity premia, so it is not a forecast.",
+  },
+  {
+    term: "1Y fwd", aliases: ["forward curve", "forward rate", "one-year forward", "forward"], functions: ["GC"],
+    definition: "The curve today's yields price for one year from now. It includes term premia, so it is not a forecast.",
+  },
+  {
+    term: "Zero-coupon yield", aliases: ["zero curve", "spot rate", "spot curve"], functions: ["GC"],
+    definition: "The yield of a single payment at that maturity, with no coupons in between. The Gilt curve is a zero-coupon curve.",
+  },
+  {
+    term: "Euro AAA", aliases: ["euro area curve", "aaa curve", "ecb curve"], functions: ["GC"],
+    definition: "The ECB's euro area yield curve, built from the bonds of AAA-rated euro area governments.",
+  },
+  {
+    term: "Bund", aliases: ["bunds", "german bund", "german government bond"], functions: ["GC"],
+    definition: "A German federal government bond, the benchmark for euro area rates.",
+  },
+  {
+    term: "Gilt", aliases: ["gilts", "uk gilt"], functions: ["GC"],
+    definition: "A UK government bond.",
+  },
+  {
+    term: "JGB", aliases: ["jgbs", "japanese government bond"], functions: ["GC"],
+    definition: "A Japanese government bond.",
+  },
+  // Money markets (BTMM).
+  {
+    term: "SOFR", aliases: ["secured overnight financing rate", "repo rate"], functions: ["BTMM", "WIRP"],
+    definition: "Secured Overnight Financing Rate: the cost of borrowing cash overnight against Treasuries (repo). The main US dollar benchmark rate.",
+  },
+  {
+    term: "EFFR", aliases: ["effective fed funds rate", "effective federal funds rate", "fed funds rate", "fed funds"], functions: ["BTMM", "WIRP"],
+    shown: ["EFFR", "effr"],
+    definition: "Effective federal funds rate: the typical rate banks pay each other for unsecured overnight loans. The Fed steers it inside its target range.",
+  },
+  {
+    term: "IORB", aliases: ["interest on reserve balances", "interest on reserves"], functions: ["BTMM"],
+    definition: "Interest on reserve balances: the rate the Fed pays banks on money they keep at the Fed. It holds fed funds below the top of the target range.",
+  },
+  {
+    term: "OBFR", aliases: ["overnight bank funding rate"], functions: ["BTMM"],
+    definition: "Overnight bank funding rate: like EFFR, but also counting the overnight eurodollar borrowing of US banks.",
+  },
+  {
+    term: "Overnight RRP", aliases: ["rrp", "on rrp", "reverse repo", "reverse repurchase"], functions: ["BTMM"],
+    definition: "Cash that money funds and others lend the Fed overnight through its reverse repo facility. Falling usage means that cash went elsewhere, often into bills.",
+  },
+  {
+    term: "Treasury account", aliases: ["tga", "treasury general account"], functions: ["BTMM"],
+    definition: "The US government's cash account at the Fed. When it grows, money leaves bank reserves.",
+  },
+  {
+    term: "Bank reserves", aliases: ["reserves", "reserve balances"], functions: ["BTMM"],
+    definition: "Money banks hold in their accounts at the Fed, as a weekly average.",
+  },
+  {
+    term: "Fed assets", aliases: ["fed balance sheet", "balance sheet", "walcl"], functions: ["BTMM"],
+    definition: "Everything the Fed owns, mostly Treasuries and mortgage bonds bought to support the economy.",
+  },
+  {
+    term: "Net liquidity", aliases: ["liquidity"], functions: ["BTMM"],
+    definition: "Fed assets minus the Treasury account minus overnight RRP: a rough gauge of the dollars the Fed leaves in markets, not a forecast.",
+  },
+  {
+    term: "Pctl 1Y", aliases: ["percentile", "1y percentile", "pctl"], functions: ["BTMM", "WIRP"],
+    definition: "Where today's value ranks against the past year of the same series: 100 is the highest, 0 the lowest.",
+  },
+  // US rate path (WIRP).
+  {
+    term: "FOMC", aliases: ["federal open market committee", "fed meeting", "fomc meeting"], functions: ["WIRP"],
+    definition: "The Federal Open Market Committee, which sets the fed funds target range at eight scheduled meetings a year.",
+  },
+  {
+    term: "Target midpoint", aliases: ["target range", "fed funds target", "midpoint"], functions: ["WIRP"],
+    shown: ["Target midpoint", "targetLower", "targetUpper"],
+    definition: "The middle of the Fed's fed funds target range, the policy rate a meeting decides.",
+  },
+  {
+    term: "Implied rate", aliases: ["implied", "futures implied rate"], functions: ["WIRP"],
+    definition: "100 minus a futures price: the rate the contract is priced to settle on. For fed funds futures that is the month's average EFFR.",
+  },
+  {
+    term: "Moves", aliases: ["priced moves", "hikes", "cuts"], functions: ["WIRP"],
+    definition: "How many 25bp rate moves are priced by that meeting, counted from today: +1.00 is one hike, -0.50 half a cut.",
+  },
+  {
+    term: "P(move)", aliases: ["move probability", "probability", "odds"], functions: ["WIRP"],
+    definition: "The odds of a 25bp move at that meeting alone, read from the step in the implied rate since the meeting before. Above 100% means more than one move is priced.",
+  },
+  {
+    term: "Fed funds futures", short: "ZQ", aliases: ["fed funds contracts", "30-day fed funds"], functions: ["WIRP"],
+    shown: ["Fed funds contracts"],
+    definition: "CME futures that settle on a month's average EFFR. The meeting path is read from them.",
+  },
+  {
+    term: "SOFR futures", short: "SR3", aliases: ["sofr contracts", "three-month sofr"], functions: ["WIRP"],
+    shown: ["SOFR contracts"],
+    definition: "CME three-month SOFR futures, settled on SOFR compounded over a quarter. They price rates further out but give no meeting odds.",
+  },
+  {
+    term: "Following-month", aliases: ["following-month method"], functions: ["WIRP"],
+    shown: ["following-month"],
+    definition: "A meeting's rate read from the next month's fed funds contract, when that month holds no other meeting.",
+  },
+  {
+    term: "Monthly-weighted", aliases: ["monthly-weighted method", "calendar weighting"], functions: ["WIRP"],
+    shown: ["monthly-weighted"],
+    definition: "A meeting's rate read from its own month's contract by weighting the days before and after it, when the next month holds another meeting.",
+  },
+  // Energy futures (FUT, CTM).
+  {
+    term: "TTF", aliases: ["title transfer facility", "dutch ttf", "dutch gas", "european gas", "eu gas"], functions: ["FUT", "CTM"],
+    shown: ["TTF", "Dutch TTF Gas"],
+    definition: "Title Transfer Facility, the Dutch gas hub whose price is Europe's gas benchmark. Its futures quote in euros per MWh.",
+  },
+  {
+    term: "Henry Hub", aliases: ["henry hub gas", "us gas", "nymex natural gas"], functions: ["FUT", "CTM"],
+    definition: "The Louisiana gas hub NYMEX natural gas (NG) delivers at, the US gas benchmark. It quotes in dollars per MMBtu.",
+  },
+  {
+    term: "MWh", aliases: ["megawatt-hour", "megawatt hour", "eur/mwh", "mwh vs mmbtu"], functions: ["FUT", "CTM"],
+    definition: "Megawatt-hour, the energy unit European gas and power are priced in. 1 MWh is about 3.412 MMBtu.",
+  },
+  {
+    term: "MMBtu", aliases: ["million btu", "million british thermal units", "usd/mmbtu", "mmbtu vs mwh"], functions: ["FUT", "CTM"],
+    definition: "Million British thermal units, the unit US gas is priced in. A TTF price in EUR/MWh divided by 3.412 is EUR/MMBtu, comparable to NG once in dollars.",
+  },
+  {
+    term: "EUA", aliases: ["eu allowance", "eu allowances", "eu ets", "carbon allowance", "carbon allowances", "eu carbon"], functions: ["FUT"],
+    definition: "EU Allowance: the right to emit one tonne of CO2 under the EU Emissions Trading System, priced in euros per tonne.",
+  },
+  {
+    term: "Front month", aliases: ["front-month", "front contract", "continuous contract", "front-month contract"], functions: ["FUT", "CTM"],
+    definition: "The nearest contract still trading. FUT quotes each root's front month by its continuous symbol (TTF=F), which rolls to the next contract as one expires.",
+  },
+  // Perpetual futures (PERP).
+  {
+    term: "Perpetual", short: "perp", aliases: ["perps", "perpetual future", "perpetual futures", "perpetual swap", "perpetual contract", "perpetual market"],
+    functions: ["PERP"],
+    definition: "A futures contract with no expiry date, so a position can be held for as long as its margin lasts. "
+      + "The funding rate keeps its price close to the asset it tracks.",
+  },
+  {
+    term: "Funding rate", aliases: ["funding", "funding payment", "funding fee", "funding 8h"], functions: ["PERP"],
+    shown: ["Funding %/int", "Funding 8h", "Paid %/int"],
+    definition: "A regular payment between the two sides of a perpetual contract, set to pull its price toward the asset's. "
+      + "Positive means longs pay shorts, negative means shorts pay longs.",
+  },
+  {
+    term: "Open interest", short: "OI", aliases: ["open interest usd"], functions: ["PERP"],
+    definition: "The total value of contracts that are open and not yet closed, counting each buyer and seller pair once, usually in dollars. "
+      + "It rises as new positions open and falls as they close.",
+  },
+  {
+    term: "Premium", aliases: ["mark premium"], functions: ["PERP"],
+    definition: "How far a perpetual's price sits above or below the reference price it tracks, as a percent. "
+      + "Positive means buyers are paying up for the contract; funding pulls it back toward zero.",
+  },
+];
+
+const ANSI = /\x1b\[[0-9;]*m/g;
+
+/** Letters and digits only, lower case: `stop-out`, `Stop Out` and `stopout` are one lookup. */
+function lookupKey(text: string): string {
+  return text.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+function words(text: string): string[] {
+  return text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
+
+function names(entry: GlossaryEntry): string[] {
+  return [entry.term, ...(entry.short ? [entry.short] : []), ...entry.aliases];
+}
+
+export interface GlossaryLookup {
+  /** The entries the query names: by the term, its abbreviation or an alias. */
+  exact: GlossaryEntry[];
+  /** The others whose names start a word with each word of the query: `stop-out` finds stop-out vs average. */
+  partial: GlossaryEntry[];
+}
+
+// Shorter words (the `b` and `c` of `B/C`) would find half the glossary.
+const MIN_PARTIAL_WORD = 3;
+
+export function lookupGlossary(query: string): GlossaryLookup {
+  const key = lookupKey(query);
+  if (!key) return { exact: [], partial: [] };
+  const exact = GLOSSARY.filter((entry) => names(entry).some((name) => lookupKey(name) === key));
+  const wanted = words(query).filter((word) => word.length >= MIN_PARTIAL_WORD);
+  const partial = wanted.length === 0 ? [] : GLOSSARY.filter((entry) => {
+    if (exact.includes(entry)) return false;
+    const have = names(entry).flatMap(words);
+    return wanted.every((word) => have.some((name) => name.startsWith(word)));
+  });
+  return { exact, partial };
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** The label as a whole token of the text: `bp` in `Chg bp` but not in `+9bp` or `bps`. */
+function showsLabel(text: string, label: string): boolean {
+  return new RegExp(`(?<![A-Za-z0-9])${escapeRegExp(label)}(?![A-Za-z0-9])`).test(text);
+}
+
+/** The glossary entries a function's report shows, in glossary order. */
+export function reportGlossary(token: string, reportText: string): GlossaryEntry[] {
+  const text = reportText.replace(ANSI, "");
+  const upper = token.toUpperCase();
+  return GLOSSARY.filter((entry) => entry.functions.includes(upper)
+    && (entry.shown ?? [entry.term, ...(entry.short ? [entry.short] : [])]).some((label) => showsLabel(text, label)));
+}
+
+function textWidth(): number {
+  return Math.min(cliTerminalWidth() ?? 100, 100);
+}
+
+function displayTerm(entry: GlossaryEntry): string {
+  return entry.short ? `${entry.term} (${entry.short})` : entry.term;
+}
+
+/** Each entry's term and meaning, side by side where the width allows. */
+export function renderGlossaryEntries(entries: readonly GlossaryEntry[]): string[] {
+  return renderDefinitions(entries.map((entry) => [displayTerm(entry), entry.definition] as const), {
+    width: textWidth(),
+    termStyle: cliStyles.bold,
+  });
+}
+
+/** What `--explain` adds under a report: the terms it shows, or a note that it shows none. */
+export function renderReportGlossary(token: string, entries: readonly GlossaryEntry[]): string {
+  if (entries.length === 0) {
+    return wrapText(`${token} shows no glossary terms. gloomberb catalog glossary lists every term.`, textWidth())
+      .map((line) => cliStyles.muted(line)).join("\n");
+  }
+  return [renderSection("Terms"), ...renderGlossaryEntries(entries)].join("\n");
+}
+
+/** Items joined by commas into lines of `width`, never breaking inside an item. */
+function commaLines(items: readonly string[], width: number): string[] {
+  const lines: string[] = [];
+  let line = "";
+  for (const item of items) {
+    const next = line ? `${line}, ${item}` : item;
+    if (line && next.length + 1 > width) {
+      lines.push(`${line},`);
+      line = item;
+    } else {
+      line = next;
+    }
+  }
+  return line ? [...lines, line] : lines;
+}
+
+/** `catalog glossary`: every term, under the function that shows it first. */
+export function renderGlossaryIndex(): string {
+  const groups = new Map<string, string[]>();
+  for (const entry of GLOSSARY) {
+    const owner = entry.functions[0]!;
+    groups.set(owner, [...(groups.get(owner) ?? []), displayTerm(entry)]);
+  }
+  const width = textWidth();
+  const labelWidth = Math.max(...[...groups.keys()].map((owner) => owner.length)) + 4;
+  return [
+    `${renderSection("Glossary")} ${cliStyles.muted(`(${GLOSSARY.length})`)}`,
+    ...[...groups].flatMap(([owner, terms]) => commaLines(terms, Math.max(20, width - labelWidth)).map((line, index) => (
+      index === 0 ? `  ${cliStyles.command(owner)}${" ".repeat(labelWidth - 2 - owner.length)}${line}` : `${" ".repeat(labelWidth)}${line}`
+    ))),
+    "",
+    ...wrapText("gloomberb catalog glossary <term> explains one; fn <function> --explain adds the terms a report shows.", width)
+      .map((line) => cliStyles.muted(line)),
+  ].join("\n");
+}
+
+/** The JSON form of an entry. */
+export function glossaryRecord(entry: GlossaryEntry): Record<string, unknown> {
+  return {
+    term: entry.term,
+    ...(entry.short ? { short: entry.short } : {}),
+    aliases: entry.aliases,
+    functions: entry.functions,
+    definition: entry.definition,
+  };
+}

package/src/cli/history-rows.ts

@@ -8,6 +8,9 @@ import {
   RANGE_HISTORY_RESOLUTION,
   type ManualChartResolution,
 } from "../time-series/resolution";
+import { classifyInstrumentType } from "../tickers/instrument-kind";
+import { isRoundTheClockCoin } from "../utils/crypto-pair";
+import { currencyPairCode } from "../utils/currency-pair";
 import { currencyUnitLabel } from "../utils/currency-units";
 import { getPricePointTimestamp } from "../utils/price-history";
 import { pricePointIntegrityFlags, pricePointValues } from "../utils/price-history-integrity";
@@ -196,15 +199,16 @@ export interface HistoryUnit {
 }
 
 /**
- * What the prices are in. An FX pair is named by its symbol (ZAR=X is ZAR per
- * USD, EURUSD=X is USD per EUR), an index is in points, and anything else is
- * in the currency its quote states, a sub-unit named as such. Without one the
- * unit is unknown rather than guessed from the exchange.
+ * What the prices are in. An FX pair is named by its listing (ZAR=X is ZAR per
+ * USD; EURUSD=X, EUR/USD and EURUSD:CCY are USD per EUR), an index is in
+ * points, and anything else is in the currency its quote states, a sub-unit
+ * named as such. Without one the unit is unknown rather than guessed from the
+ * exchange.
  */
-export function historyUnit(symbol: string, quote: { currency?: string; instrumentType?: string } | null | undefined): HistoryUnit {
-  const pair = /^([A-Z]{3})([A-Z]{3})?=X$/.exec(symbol.trim().toUpperCase());
+export function historyUnit(listing: string, quote: { currency?: string; instrumentType?: string } | null | undefined): HistoryUnit {
+  const pair = currencyPairCode(listing.trim().toUpperCase());
   if (pair) {
-    const [base, counter] = pair[2] ? [pair[1]!, pair[2]] : ["USD", pair[1]!];
+    const [base, counter] = [pair.slice(0, 3), pair.slice(3)];
     return { kind: "pair", currency: counter, unit: `${counter} per ${base}` };
   }
   if (quote?.instrumentType?.trim().toUpperCase() === "INDEX") return { kind: "points", currency: null, unit: "index points" };
@@ -259,6 +263,43 @@ export function historyNotes(
   return notes;
 }
 
+/** Gaps listed by date before the rest are only counted. */
+const LISTED_GAPS = 3;
+
+/**
+ * "No bar for 2026-10-10": the days a coin, which trades every day, has no
+ * daily bar for between its first and last bar. Days before the first bar are
+ * before the listing. A market that closes skips weekends and holidays, so its
+ * gaps say nothing and get no note.
+ */
+export function historyGapNote(
+  rows: readonly Pick<HistoryRow, "date" | "interval">[],
+  market: { listing: string; exchange?: string; instrumentType?: string },
+): string | null {
+  const everyDay = isRoundTheClockCoin(market.listing, market.exchange)
+    || classifyInstrumentType(market.instrumentType) === "crypto";
+  if (!everyDay || rows[0]?.interval !== "1d") return null;
+  const days = new Set(rows.map((row) => Date.parse(`${row.date.slice(0, 10)}T00:00:00Z`)).filter(Number.isFinite));
+  const sorted = [...days].sort((left, right) => left - right);
+  const gaps: Array<[number, number]> = [];
+  for (const [index, day] of sorted.slice(1).entries()) {
+    const previous = sorted[index]!;
+    if (day - previous > DAY_MS) gaps.push([previous + DAY_MS, day - DAY_MS]);
+  }
+  if (!gaps.length) return null;
+  const date = (time: number) => new Date(time).toISOString().slice(0, 10);
+  const length = (gaps: Array<[number, number]>) => gaps.reduce((count, [from, to]) => count + (to - from) / DAY_MS + 1, 0);
+  // The latest gaps by date, the rest as a count.
+  const shown = gaps.slice(-LISTED_GAPS);
+  const earlier = length(gaps) - length(shown);
+  const listed = [
+    ...earlier > 0 ? [`${earlier} earlier ${earlier === 1 ? "day" : "days"}`] : [],
+    ...shown.map(([from, to]) => from === to ? date(from) : `${date(from)} to ${date(to)}`),
+  ];
+  const list = listed.length > 1 ? `${listed.slice(0, -1).join(", ")} and ${listed.at(-1)}` : listed[0];
+  return `${length(gaps) === 1 ? "No bar" : "No bars"} for ${list}`;
+}
+
 /** "37 of 251 bars have high below open or close in the source data; ...", or null when every bar agrees. */
 export function historyFlagNote(rows: readonly Pick<HistoryRow, "flag">[]): string | null {
   const flagged = rows.filter((row) => row.flag);

package/src/cli/index-roots.ts

@@ -49,3 +49,10 @@ export function indexRootTryLine(root: IndexRoot, command = "quote"): string {
 export function indexRootAlsoLine(root: IndexRoot, command = "quote"): string {
   return `also ${root.symbol} ${root.name} (gloomberb ${command} ${root.symbol})`;
 }
+
+/** Cboe's Treasury yield indices: 13-week bill, 5-, 10- and 30-year notes. Each level is a yield in percent. */
+const YIELD_INDEX_SYMBOLS: ReadonlySet<string> = new Set(["^IRX", "^FVX", "^TNX", "^TYX"]);
+
+export function isYieldIndexSymbol(symbol: string): boolean {
+  return YIELD_INDEX_SYMBOLS.has(symbol.trim().toUpperCase());
+}

package/src/cli/index.ts

@@ -19,10 +19,11 @@ import {
   TABLE_SECTION_OPTION,
   type CliHelpEntry,
 } from "./help";
-import { parsePaneFunctionArgs } from "./pane-functions/options";
+import { parsePaneFunctionArgs, SHOT_SIZE_LIMITS } from "./pane-functions/options";
 import { checkCliCommandOptions } from "./command-options";
 import { asUsageError, fail, inferCliErrorOptions, printCliError } from "./errors";
-import { setCliColorEnabledOverride, setCliWidthOverride } from "../utils/cli-output";
+import { cliStyles, setCliColorEnabledOverride, setCliWidthOverride } from "../utils/cli-output";
+import { setDisplayTimeZone } from "../utils/utc-time";
 import { search, searchCandidatesForCli, buildSearchReport } from "./commands/search";
 import { ticker } from "./commands/ticker";
 import { requireOneArg, takeOption } from "./commands/command-utils";
@@ -37,6 +38,8 @@ import { listPlugins, updatePlugins } from "./commands/plugins";
 import { installListedPlugin, removePlugin } from "../plugins/installer";
 import { runPaneCatalog, runPaneFunction, runPaneScreenshot } from "./pane-functions";
 
+const { width: SHOT_WIDTH, height: SHOT_HEIGHT } = SHOT_SIZE_LIMITS;
+
 function createCoreCliCommands(
   helpEntries: () => CliHelpEntry[],
   lookupCommand: (token: string) => CliCommandDef | null,
@@ -121,15 +124,21 @@ function createCoreCliCommands(
     {
       name: "catalog",
       aliases: ["functions", "capabilities"],
-      description: "Find market functions to run with fn or capture with shot",
+      description: "Find market functions to run with fn or capture with shot, or look up a term",
       help: {
         group: CLI_COMMAND_GROUPS.functions,
-        usage: ["catalog [query] [--all] [--bot-safe]"],
+        usage: ["catalog [query] [--all] [--bot-safe]", "catalog glossary [term]", "catalog explain <term>"],
         options: [
           { flags: "--all", description: "List every match instead of the first 25" },
           { flags: "--bot-safe, --botsafe", description: "Only functions with a verified unattended report" },
         ],
-        examples: ["catalog", "catalog options", "catalog HP"],
+        sections: [{
+          title: "Glossary",
+          lines: [
+            "catalog glossary lists the rates, auction, energy and perpetual-futures terms the functions show, such as bid-to-cover, SOFR, TTF or funding rate; with a term, or as catalog explain <term>, it prints what that term means. A search names the terms it matches too.",
+          ],
+        }],
+        examples: ["catalog", "catalog options", "catalog HP", "catalog glossary stop-out"],
       },
       execute: async (args, ctx) => {
         await runPaneCatalog(args, ctx);
@@ -145,6 +154,7 @@ function createCoreCliCommands(
         options: [
           { flags: "--<option> <value>", description: "A function setting; gloomberb catalog <function> lists them" },
           { flags: "--require-bot-safe", description: "Fail unless the function has a verified, complete report" },
+          { flags: "--explain", description: "Follow the report with what its terms mean (text and JSON; CSV keeps the rows)" },
           {
             ...TABLE_SECTION_OPTION,
             description: `${TABLE_SECTION_OPTION.description} (CALLS keeps --section for the transcript part)`,
@@ -158,6 +168,7 @@ 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 AUCT --explain",
         ],
       },
       execute: async (args, ctx) => {
@@ -174,8 +185,8 @@ function createCoreCliCommands(
         usage: ["shot <function> [argument] [options]"],
         options: [
           { flags: "--output <path>", description: "PNG to write; defaults to gloomberb-<function>-<argument>.png in this folder" },
-          { flags: "--width <px>", description: "Image width, 720 to 2400 (default 1280)" },
-          { flags: "--height <px>", description: "Image height, 360 to 1800 (default 720)" },
+          { flags: "--width <px>", description: `Layout width, ${SHOT_WIDTH.min} to ${SHOT_WIDTH.max} (default 1280). The PNG is drawn at twice the size: ${SHOT_WIDTH.min * 2} to ${SHOT_WIDTH.max * 2} px wide` },
+          { flags: "--height <px>", description: `Layout height, ${SHOT_HEIGHT.min} to ${SHOT_HEIGHT.max} (default 720), so ${SHOT_HEIGHT.min * 2} to ${SHOT_HEIGHT.max * 2} px tall` },
           { flags: "--theme <id>", description: "Render with another theme, such as amber or colorblind; gloomberb config themes lists them" },
           { flags: "--scale <n>", description: "Text scale from 0.5 to 4 (default 1)" },
           { flags: "--watermark <label>", description: "Label drawn in the pane title bar" },
@@ -224,6 +235,7 @@ function createCoreCliCommands(
         if (!ref) {
           fail("Usage: gloomberb install <user/repo>");
         }
+        console.error(cliStyles.warning("Runs with your full permissions. Read the source first."));
         await installListedPlugin(ref);
       },
     },
@@ -317,6 +329,8 @@ function listedCommands(registry: CliCommandRegistry) {
 
 async function createRegistry(options: DispatchCliOptions = {}): Promise<CliCommandRegistry> {
   const config = await loadCliConfigIfAvailable();
+  // Every time a command prints follows the reader's zone from here on.
+  setDisplayTimeZone(config?.timezone);
   let registry: CliCommandRegistry | null = null;
   const coreCommands = createCoreCliCommands(
     () => listedCommands(registry!).map(({ command, source }) => ({ command, source })),

package/src/cli/known-gaps.ts

@@ -0,0 +1,27 @@
+/**
+ * Data people look for that no source here carries yet, each with the nearest
+ * thing the app does quote. `search` and `catalog` answer a query that names
+ * one with this line instead of pointing at each other. One entry per gap;
+ * every proxy named is a listing `gloomberb quote` answers (checked
+ * 2026-10-11: CO2:LSE is the physical EUA ETC, while a bare CO2 is a Brent
+ * future).
+ */
+const KNOWN_GAPS: ReadonlyArray<{ terms: readonly string[]; message: string }> = [
+  {
+    terms: ["EUA", "EUAs", "EU ETS", "EU allowance", "EU allowances", "EU carbon", "carbon", "carbon allowance", "carbon allowances",
+      "carbon price", "carbon prices", "carbon credits", "emission allowances", "emissions allowances"],
+    message: "No EU carbon price (EUA) yet. Proxies: CO2:LSE, KRBN.",
+  },
+];
+
+/** Letters and digits only, lower case: `EU-ETS`, `eu ets` and `EUETS` are one lookup. */
+function lookupKey(text: string): string {
+  return text.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+
+/** The line for a query that names a known gap as a whole ("carbon allowances", "EUA"), else null. */
+export function knownGapMessage(query: string): string | null {
+  const key = lookupKey(query);
+  if (!key) return null;
+  return KNOWN_GAPS.find((gap) => gap.terms.some((term) => lookupKey(term) === key))?.message ?? null;
+}