gloomberb 0.18.3 → 0.18.4

package/src/cli/pane-functions/financial-ratio-shot.ts

@@ -67,7 +67,7 @@ function ratioShot(resolved: ResolvedPaneFunction, payload: DesktopPaneShotPaylo
   return { symbol, financials, tab, period, model: ratioTableForFinancials(financials, tab, period, history) };
 }
 
-const hasRatio = ({ model, tab }: RatioShot, index: number) => tab.ratios.some((def) => (
+const hasRatio = ({ model }: RatioShot, index: number) => model.ratios.some((def) => (
   typeof model.cells.get(def.id)?.[index]?.value === "number"
 ));
 
@@ -106,7 +106,7 @@ export function financialRatioShotEvidence(
       date: statement.date,
       periodEnd: ratioPeriodEnd(statement),
       price: typeof price === "number" ? price : null,
-      ratios: shot.tab.ratios.flatMap((def) => {
+      ratios: shot.model.ratios.flatMap((def) => {
         const value = shot.model.cells.get(def.id)![index]!.value;
         return typeof value === "number" ? [{ id: def.id, label: def.label, value }] : [];
       }),

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

@@ -12,6 +12,8 @@ import { localTimeSuffix, parseReportTime, type ReportTime } from "../../utils/u
 import { isRecord } from "../../utils/guards";
 import { latestRegularSessionClose, readIndexSession } from "../../market-data/market/freshness";
 import { reportMarketSession, reportVenueSessionDates, type ReportMarket, type SessionObservation, type VenueSessionDate } from "./market-session";
+import { savedCopyShownAt } from "../../data/saved-copies";
+import { releasedText } from "../../utils/release-date";
 
 /**
  * The four states of docs/usage.md#how-current-a-report-is, plus `unreported`
@@ -23,10 +25,26 @@ type ReportFreshnessStatus = HeadlessFreshnessStatus | "unreported";
 /** What every `fn` report cites about its data, in its JSON and its last text line. */
 export interface ReportFreshness {
   source: string;
-  /** Newest observation: an ISO instant in UTC, or an ISO date. Null when nothing in the data is dated. */
+  /**
+   * Newest observation: an ISO instant in UTC, or an ISO date. For a figure
+   * dated by the period it covers whose release is known (`referencePeriod`),
+   * the day or time it was released. Null when nothing in the data is dated.
+   */
   asOf: string | null;
+  /**
+   * The newest observation's own date when `asOf` is its release: the first
+   * day of its period with `periodicity` (`2026-09-01` is Sep 2026), else the
+   * day it is dated by (a weekly figure's week end). The status line then
+   * reads `Sep 2026, released Tue 20 Oct`.
+   */
+  referencePeriod?: string;
   /** Oldest observation, when it is more than a day older than `asOf`. */
   oldest?: string;
+  /**
+   * How often the oldest observation publishes, when its rows say and it is
+   * not `periodicity` (a quarterly figure beside a monthly one); null for a day.
+   */
+  oldestPeriodicity?: ReportFreshness["periodicity"] | null;
   /** With a declared `citeOldest`: the oldest observation whenever it is older than `asOf`. Exports cite it. */
   oldestObservation?: string;
   status: ReportFreshnessStatus;
@@ -86,18 +104,42 @@ export interface ReportFreshness {
    * oldest observation) to when this report was built: `oldest 9 min`.
    */
   oldestAgeMinutes?: number;
+  /** The data states no feed (`status` is `unreported`) and its line says only its time and age (`ageOnly`). */
+  ageOnly?: true;
   /** What the newest observation is, said before its time: `newest story Tue 29 Sep 2026 20:17 UTC`. */
   asOfLabel?: string;
   /** What the figures are, said after the status: `funding = current estimate, pays 08:00 UTC`. */
   note?: string;
+  /** Shorter forms of `note`, in the order a capture's line too long for it tries them. */
+  noteVariants?: string[];
   /** When the figures reach readers and when the next are due, said right after the as-of date. */
   schedule?: string;
+  /** Shorter forms of `schedule`, in the order a status line too long for it tries them. */
+  scheduleVariants?: string[];
   /** Who published the figures, when the data names them. */
   publisher?: string;
   /** When the publisher released the data, an ISO instant in UTC or an ISO date, when the data states it. */
   publishedAt?: string;
   /** When this report was built. */
   retrievedAt: string;
+  /**
+   * Refreshing the data failed and a copy saved earlier answered: when that
+   * copy was saved, an ISO instant in UTC. The status line then says
+   * `couldn't refresh; saved 21:49 UTC` in place of how current the data is.
+   */
+  savedAt?: string;
+}
+
+/**
+ * The freshness a command prints, saying when what it shows (`shown`: its
+ * rows, or the data its line is drawn from) came from a copy saved earlier
+ * because refreshing it failed (`collectSavedCopies`): its status line then
+ * reads `couldn't refresh; saved 21:49 UTC` instead of live or delayed.
+ */
+export function withSavedCopy<F extends ReportFreshness | undefined>(freshness: F, shown: unknown): F {
+  if (!freshness || freshness.savedAt) return freshness;
+  const savedAt = savedCopyShownAt(shown);
+  return savedAt == null ? freshness : { ...freshness, savedAt: new Date(savedAt).toISOString() };
 }
 
 /** One source's newest observation: an ISO instant in UTC. */
@@ -140,6 +182,40 @@ interface Observations {
   units: ReportTime[];
   /** Metadata and snapshot stamps: candidates for `asOf` only. */
   extra: ReportTime[];
+  /** A unit dated by the period it covers whose row says when it was released (`releasedOn`), and how often. */
+  releases?: Map<ReportTime, UnitRelease>;
+}
+
+interface UnitRelease {
+  released: ReportTime | null;
+  periodicity?: NonNullable<HeadlessPaneFreshness["periodicity"]>;
+}
+
+const PERIODICITIES = new Set<unknown>(["monthly", "quarterly", "semiannual", "annual"]);
+
+/** What a dated row says of its release: `releasedOn` and its `periodicity`, when it names either. */
+function readUnitRelease(record: Record<string, unknown>, time: ReportTime, now: number, observations: Observations): void {
+  const hasPeriodicity = PERIODICITIES.has(record.periodicity);
+  if (!time.dateOnly || (record.releasedOn == null && !hasPeriodicity)) return;
+  (observations.releases ??= new Map()).set(time, {
+    released: releaseTime(record.releasedOn as HeadlessPaneFreshness["releasedOn"], time, now),
+    ...(hasPeriodicity ? { periodicity: record.periodicity as UnitRelease["periodicity"] } : {}),
+  });
+}
+
+/**
+ * The release and periodicity of the newest observation when the rows dated
+ * `asOf` all say the same one; nothing when any of them names none, or they
+ * disagree (a monthly and a weekly figure dated the same day).
+ */
+function newestUnitRelease(observations: Observations, asOf: ReportTime): UnitRelease | null {
+  if (observations.extra.some((time) => time.time > asOf.time)) return null;
+  const newest = observations.units.filter((time) => time.time === asOf.time);
+  const releases = newest.map((time) => observations.releases?.get(time) ?? null);
+  const [first] = releases;
+  if (!first || releases.some((release) => !release
+    || release.released?.time !== first.released?.time || release.periodicity !== first.periodicity)) return null;
+  return first;
 }
 
 function emptySignals(): FeedSignals {
@@ -231,7 +307,10 @@ function collect(
       ?? (observedKey ? null : observedTime(row, now, UPDATE_KEYS));
     if (!ignoreStaleFlags) readUnitStale(row, time, signals);
     readSession(row, time, signals);
-    if (time) observations.units.push(time);
+    if (time) {
+      observations.units.push(time);
+      readUnitRelease(row, time, now, observations);
+    }
   }
   if (definition.shape === "series" && !declaredObservations) {
     for (const series of (result as HeadlessSeriesResult).series) {
@@ -359,6 +438,17 @@ function declaredSources(declared: HeadlessPaneFreshness, now: number): Array<{
   });
 }
 
+/**
+ * A declared release of the newest observation, when it is after the
+ * observation's day (or a time on it) and not in the future; null for anything
+ * else, a figure released the day it is dated by among them.
+ */
+function releaseTime(declared: HeadlessPaneFreshness["releasedOn"], observed: ReportTime, now: number): ReportTime | null {
+  const released = parseReportTime(declared);
+  if (!released || released.time < observed.time || released.time > now + FUTURE_TOLERANCE_MS) return null;
+  return released.dateOnly && released.time === observed.time ? null : released;
+}
+
 /** A declared bar period still forming, its last day read as a date; null for anything else. */
 function readPeriodToDate(declared: HeadlessPaneFreshness["periodToDate"], now: number): { period: "week" | "month"; through: ReportTime | null } | null {
   if (declared?.period !== "week" && declared?.period !== "month") return null;
@@ -375,7 +465,7 @@ function resolveFreshness({ declared, signals, observations, now }: FreshnessInp
   const asOf = declaredAsOf ?? periodToDate?.through ?? newest([...observations.units, ...observations.extra]);
   // The oldest source, not the newest, says how far behind the view can be.
   const agedFrom = sources.length ? oldest(sources.map(({ time }) => time))
-    : declared.oldestAge ? oldest(observations.units) ?? asOf : null;
+    : declared.oldestAge || declared.ageOnly ? oldest(observations.units) ?? asOf : null;
   const oldestAgeMinutes = agedFrom && !agedFrom.dateOnly ? Math.max(0, Math.floor((now - agedFrom.time) / 60_000)) : null;
   // A loader that dates its data itself also says how old the oldest part is, or nothing;
   // `oldest: null` says the rows are a history, whose first entry is not stale data.
@@ -441,7 +531,10 @@ function resolveFreshness({ declared, signals, observations, now }: FreshnessInp
   const asOfClose = closeDate && asOf && !declaredAsOf ? closeDate : null;
   const tradingDayMarket = asOfClose ? closeMarket
     : asOf?.dateOnly ? declared.tradingDayMarket?.trim() || null : null;
-  const periodicity = declared.periodicity && asOf?.dateOnly ? declared.periodicity : undefined;
+  // Rows dated by the period they cover can say how often they publish and when the newest was released.
+  const unitRelease = asOf && !declaredAsOf && !periodToDate ? newestUnitRelease(observations, asOf) : null;
+  const periodicity = (declared.periodicity ?? unitRelease?.periodicity) && asOf?.dateOnly
+    ? declared.periodicity ?? unitRelease?.periodicity : undefined;
   // Rows that are quotes (a feed, a venue's session) keep the market line, even on a dataset's pane.
   const quoted = rowsAreQuotes(signals);
   // A dataset disseminated with a delay (DTCC's swap tape) lags its newest observation all the same.
@@ -450,14 +543,28 @@ function resolveFreshness({ declared, signals, observations, now }: FreshnessInp
   const observation = lagDays != null ? declared.observation?.trim() : undefined;
 
   const note = declared.note?.trim();
+  const noteVariants = note ? (declared.noteVariants ?? []).map((variant) => variant.trim()).filter((variant) => variant && variant !== note) : [];
   const asOfLabel = asOf ? declared.asOfLabel?.trim() : undefined;
   const schedule = declared.schedule?.trim();
+  const scheduleVariants = schedule ? (declared.scheduleVariants ?? []).map((variant) => variant.trim()).filter((variant) => variant && variant !== schedule) : [];
   const publisher = declared.publisher?.trim();
   const publishedAt = parseReportTime(declared.publishedAt);
+  // A figure dated by the period it covers is as of its release: September's permits
+  // are dated 1 Sep and were released 20 Oct. Age, staleness and the oldest stay the observation's.
+  const released = asOf?.dateOnly && !declared.dataset && !periodToDate
+    ? releaseTime(declared.releasedOn, asOf, now) ?? unitRelease?.released ?? null : null;
+  // The oldest row's own period, when the rows name theirs (a quarterly figure among daily ones).
+  const oldestRelease = !declared.periodicity && oldestTime ? observations.releases?.get(oldestTime) : undefined;
+  const oldestPeriodicity = declared.oldestPeriodicity !== undefined ? declared.oldestPeriodicity
+    : oldestRelease ? oldestRelease.periodicity ?? null : unitRelease?.periodicity ? null : undefined;
   return {
     source: declared.source?.trim() || (sources.length ? [...new Set(sources.map(({ source }) => source))].join(", ") : DEFAULT_REPORT_SOURCE),
-    asOf: asOf ? isoTime(asOf) : null,
-    ...(asOf && oldestTime && asOf.time - oldestTime.time > OLDEST_GAP_MS ? { oldest: isoTime(oldestTime) } : {}),
+    asOf: released ? isoTime(released) : asOf ? isoTime(asOf) : null,
+    ...(released && asOf ? { referencePeriod: isoTime(asOf) } : {}),
+    ...(asOf && oldestTime && asOf.time - oldestTime.time > OLDEST_GAP_MS ? {
+      oldest: isoTime(oldestTime),
+      ...(oldestPeriodicity !== undefined && (oldestPeriodicity ?? undefined) !== periodicity ? { oldestPeriodicity } : {}),
+    } : {}),
     ...(asOf && oldestUnit && oldestUnit.time < asOf.time ? { oldestObservation: isoTime(oldestUnit) } : {}),
     status,
     ...(delayMinutes != null && delayMinutes > 0 ? { delayMinutes } : {}),
@@ -475,9 +582,12 @@ function resolveFreshness({ declared, signals, observations, now }: FreshnessInp
     ...(observation ? { observation } : {}),
     ...(sources.length ? { sources: sources.map(({ source, time }) => ({ source, asOf: isoTime(time) })) } : {}),
     ...(oldestAgeMinutes != null ? { oldestAgeMinutes } : {}),
+    ...(status === "unreported" && declared.ageOnly ? { ageOnly: true as const } : {}),
     ...(asOfLabel ? { asOfLabel } : {}),
     ...(note ? { note } : {}),
+    ...(noteVariants.length > 0 ? { noteVariants } : {}),
     ...(schedule ? { schedule } : {}),
+    ...(scheduleVariants.length > 0 ? { scheduleVariants } : {}),
     ...(publisher ? { publisher } : {}),
     ...(publishedAt ? { publishedAt: isoTime(publishedAt) } : {}),
     retrievedAt: new Date(now).toISOString(),
@@ -558,7 +668,11 @@ export function deriveRenderedFreshness(
     declared: merged,
     signals,
     // Rendered rows are often a history (a news list, a filing feed), so only the newest is cited.
-    observations: { units: observed?.observations.units ?? [], extra: [...(observed?.observations.extra ?? []), ...units] },
+    observations: {
+      units: observed?.observations.units ?? [],
+      extra: [...(observed?.observations.extra ?? []), ...units],
+      ...(observed?.observations.releases ? { releases: observed.observations.releases } : {}),
+    },
     now,
   });
 }
@@ -689,7 +803,8 @@ function statusText(freshness: ReportFreshness, short = false): string {
     case "not-a-feed":
       return freshness.basis ? `not a live feed (${freshness.basis})` : "not a live feed";
     case "unreported":
-      return "status not reported";
+      // Keep any date or age, without inventing a feed status or announcing its absence.
+      return "";
     default: {
       const _exhaustive: never = freshness.status;
       return _exhaustive;
@@ -702,6 +817,19 @@ function onRetrievalDay(iso: string, retrievedAt: string): boolean {
   return iso.slice(0, 10) === retrievedAt.slice(0, 10);
 }
 
+/**
+ * What a report answered from a saved copy says in place of how current its
+ * data is: `couldn't refresh; saved 21:49 UTC`, with the day when the copy was
+ * saved on another day than the report was built.
+ */
+function savedCopyText(savedAt: string, retrievedAt: string, local: boolean): string {
+  const at = Date.parse(savedAt);
+  if (!Number.isFinite(at)) return "couldn't refresh";
+  const iso = new Date(at).toISOString();
+  const time = onRetrievalDay(iso, retrievedAt) ? `${iso.slice(11, 16)} UTC${local ? localTimeSuffix(at) : ""}` : timeText(iso, local);
+  return `couldn't refresh; saved ${time}`;
+}
+
 /** `US and XETRA`, `US, XETRA and EPA`. */
 function listText(items: readonly string[]): string {
   return items.length <= 1 ? items.join("") : `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
@@ -734,14 +862,19 @@ function asOfText(freshness: ReportFreshness, short: boolean, local: boolean, un
   const market = freshness.tradingDayMarket;
   const period = freshness.periodicity;
   const time = parseReportTime(freshness.asOf);
-  const asOf = freshness.periodToDate ? periodToDateText(freshness.periodToDate, freshness.asOf)
+  const reference = freshness.referencePeriod;
+  // `Sep 2026, released Tue 20 Oct`: the period the figure covers, then when it was released.
+  const released = reference ? releasedText(freshness.asOf, reference) : null;
+  const asOf = released && reference ? `${period ? periodText(reference, period) : dayText(reference)}, ${released}`
+    : freshness.periodToDate ? periodToDateText(freshness.periodToDate, freshness.asOf)
     : period ? `${periodText(freshness.asOf, period)} (${period})`
     : freshness.asOfClose
       ? `${tradingDayText(freshness.asOfClose, market)} close`
       : time?.dateOnly ? tradingDayText(freshness.asOf, market)
         : undated && time && onRetrievalDay(new Date(time.time).toISOString(), freshness.retrievedAt)
           ? `${new Date(time.time).toISOString().slice(11, 16)} UTC` : timeText(freshness.asOf, local);
-  const oldest = freshness.oldest && (period ? periodText(freshness.oldest, period) : dayText(freshness.oldest));
+  const oldestPeriod = freshness.oldestPeriodicity !== undefined ? freshness.oldestPeriodicity : period;
+  const oldest = freshness.oldest && (oldestPeriod ? periodText(freshness.oldest, oldestPeriod) : dayText(freshness.oldest));
   // A list dated by its newest entry names it, so the time is not read as when the list was read.
   const dated = freshness.asOfLabel ? `${freshness.asOfLabel} ${asOf}` : asOf;
   return oldest && !short && freshness.oldestAgeMinutes == null ? `${dated} (oldest ${oldest})` : dated;
@@ -817,10 +950,12 @@ interface StatusLineDetail {
   local?: "none";
   /** Leave the day off a time of the day the report was built. */
   date?: "none";
-  /** Leave out what the figures are (`funding = current estimate`). */
-  note?: "none";
-  /** Leave out when the figures are published and the next are due. */
-  schedule?: "none";
+  /** Leave out what the figures are (`funding = current estimate`), or say the shorter form at this index of `noteVariants`. */
+  note?: "none" | number;
+  /** Leave out when the figures are published and the next are due, or say the shorter form at this index of `scheduleVariants`. */
+  schedule?: "none" | number;
+  /** Leave out what not-a-feed data is (`not a live feed` for `not a live feed (weekly report)`). */
+  basis?: "none";
 }
 
 /**
@@ -836,11 +971,13 @@ function statusLineParts(freshness: ReportFreshness, detail: StatusLineDetail =
   return [
     ...(freshness.sources?.length ? sourcesAsOfParts(freshness, freshness.sources, undated)
       : [asOfText(freshness, detail.asOf === "short", local, undated)]),
-    ...(freshness.schedule && detail.schedule !== "none" ? [freshness.schedule] : []),
+    ...(freshness.schedule && detail.schedule !== "none"
+      ? [typeof detail.schedule === "number" ? freshness.scheduleVariants?.[detail.schedule] ?? freshness.schedule : freshness.schedule] : []),
     ...(freshness.oldestAgeMinutes != null ? [`oldest ${ageText(freshness.oldestAgeMinutes)}`] : []),
-    statusText(freshness, detail.status === "short"),
+    ...(freshness.savedAt ? [savedCopyText(freshness.savedAt, freshness.retrievedAt, local)]
+      : [statusText(detail.basis === "none" ? { ...freshness, basis: undefined } : freshness, detail.status === "short")].filter(Boolean)),
     ...(freshness.market && detail.market !== "none" ? [marketText(freshness.market, now, detail.market === "short", local)] : []),
-    ...(freshness.note && detail.note !== "none" ? [freshness.note] : []),
+    ...(freshness.note && detail.note !== "none" ? [typeof detail.note === "number" ? freshness.noteVariants?.[detail.note] ?? freshness.note : freshness.note] : []),
   ];
 }
 
@@ -881,7 +1018,8 @@ function datasetLineParts(freshness: ReportFreshness, asOf: string, lagDays: num
       ...(detail.source === "none" ? [] : [`Source: ${freshness.source}`]),
       `${freshness.observation} ${asOf.slice(0, 10)}`,
       lagText(lagDays),
-      ...(freshness.status === "stale" ? ["stale"] : []),
+      ...(freshness.savedAt ? [savedCopyText(freshness.savedAt, freshness.retrievedAt, false)]
+        : freshness.status === "stale" ? ["stale"] : []),
     ];
   }
   const period = freshness.periodicity;
@@ -892,10 +1030,20 @@ function datasetLineParts(freshness: ReportFreshness, asOf: string, lagDays: num
     ...(detail.source === "none" ? [] : [`Source: ${freshness.source}`]),
     `observed ${dated(asOf)}${period ? ` (${period})` : ""}${oldest}`,
     `lag ${lagDays}d`,
-    ...(stale ? [stale] : []),
+    ...(freshness.savedAt ? [savedCopyText(freshness.savedAt, freshness.retrievedAt, false)] : stale ? [stale] : []),
   ];
 }
 
+/**
+ * A line too narrow for its whole schedule keeps when the figures were
+ * published longest: the not-a-feed basis goes first, then the schedule
+ * shortens through `scheduleVariants`. Nothing for a line without them.
+ */
+function shorterSchedules(freshness: ReportFreshness, detail: StatusLineDetail): StatusLineDetail[] {
+  if (!freshness.schedule || !freshness.scheduleVariants?.length) return [];
+  return [{ ...detail, basis: "none" }, ...freshness.scheduleVariants.map((_, index) => ({ ...detail, basis: "none" as const, schedule: index }))];
+}
+
 /**
  * The plain status line of a capture: the longest of `statusLineVariants`,
  * `Fri 9 Oct close · 15 min delayed · markets closed until Mon` for quotes.
@@ -927,7 +1075,9 @@ export function paneStatusLineVariants(freshness: ReportFreshness): string[] {
   // A dataset's line has no market or local time to leave out: it reads as its report and capture do.
   if (datesObservation(freshness)) return statusLineVariants(freshness);
   const pane: StatusLineDetail = { local: "none", date: "none" };
-  const details: StatusLineDetail[] = [pane, { ...pane, market: "short" }, { ...pane, market: "short", status: "short" }, { ...pane, market: "short", status: "short", note: "none" }, { ...pane, market: "short", status: "short", note: "none", schedule: "none" }];
+  const shortest: StatusLineDetail = { ...pane, market: "short", status: "short", note: "none" };
+  const details: StatusLineDetail[] = [pane, { ...pane, market: "short" }, { ...pane, market: "short", status: "short" }, shortest,
+    ...shorterSchedules(freshness, shortest), { ...shortest, schedule: "none" }];
   return [...new Set(details.map((detail) => capitalize(statusLineParts(freshness, detail).join(" · "))))];
 }
 
@@ -964,10 +1114,11 @@ export function statusLineVariants(freshness: ReportFreshness, { source = false
   // A line that dates each source keeps every source's time and their age to
   // the last: its day goes first, then what the figures are.
   const shortest = details.at(-1)!;
-  // What the figures are goes before when they are published.
+  // What the figures are goes before when they are published, in its shorter forms first.
   const trailing: StatusLineDetail[] = [
+    ...(freshness.noteVariants ?? []).map((_, index) => ({ ...shortest, note: index })),
     ...(freshness.note ? [{ ...shortest, note: "none" as const }] : []),
-    ...(freshness.schedule ? [{ ...shortest, note: "none" as const, schedule: "none" as const }] : []),
+    ...(freshness.schedule ? [...shorterSchedules(freshness, { ...shortest, note: "none" }), { ...shortest, note: "none" as const, schedule: "none" as const }] : []),
   ];
   const variants: StatusLineDetail[] = freshness.sources?.length
     ? [{}, ...details.map((detail) => ({ ...detail, date: "none" as const })), { ...shortest, date: "none", note: "none" }]
@@ -1023,7 +1174,7 @@ export function captureStatusLine({ report: loaded, selfDated, quoted, rendered
   }
   if (report && loaded?.declaresData) return sourced(report);
   if (quoted) return plain(quoted, "quotes");
-  if (report && report.status !== "unreported") return sourced(report);
+  if (report && (report.status !== "unreported" || report.ageOnly)) return sourced(report);
   return plain(rendered(), null);
 }
 

package/src/cli/pane-functions/function-help.ts

@@ -104,6 +104,15 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     data: QUOTES,
     bloomberg: ["DES"],
   },
+  ADR: {
+    summary: "What exchange rate does a receipt's price imply? A depositary receipt beside its home listing: the ratio, both prices with when each was set, the dollar rate they imply (the CCL rate for an Argentine pair) against spot, and the receipt's premium or discount. Opens DES on its ADR vs Home tab.",
+    usage: ["ADR GGAL", "ADR TSM", "ADR GGAL.BA"],
+    keys: [key("Enter", " open the listing")],
+    data: QUOTES,
+    bloomberg: [],
+    // A tab of DES, filed under it.
+    docs: "DES",
+  },
   QQ: {
     summary: "A compact board of live quotes for any list of tickers, each with change, range and a sparkline. Good as the always-open strip in a layout.",
     usage: ["QQ NVDA, AAPL, MSFT"],
@@ -126,8 +135,8 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["GIP"],
   },
   G: {
-    summary: "Chart any series together: prices, statement lines, valuation multiples, FRED series, map series such as chokepoint transits, indicators and formulas. Series read SYMBOL:field, FRED:series or GEO:series.",
-    usage: ["G", "G NVDA:revenue, NVDA:net_income", "G XOM, GEO:HORMUZ"],
+    summary: "Chart any series together: prices, statement lines, valuation multiples, FRED series, map series such as chokepoint transits, indicators and formulas. Series read SYMBOL:field, FRED:series or GEO:series, separated by commas; tickers with spaces between them are a list too.",
+    usage: ["G", "G NVDA:revenue, NVDA:net_income", "G XOM, GEO:HORMUZ", "G AAPL MSFT"],
     keys: CHART_KEYS,
     data: { free: "Prices 15 minutes delayed, other series as published", pro: "Prices real-time for US listings, other series as published" },
     bloomberg: ["G"],
@@ -140,8 +149,8 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: [],
   },
   CMP: {
-    summary: "Price returns rebased to a shared start date for two or more tickers, so relative performance reads at a glance.",
-    usage: ["CMP NVDA, AMD, AVGO"],
+    summary: "Price returns rebased to a shared start date for two or more tickers, so relative performance reads at a glance. A leveraged or inverse fund gets its daily objective drawn from its index fund, and its decay in its own panel.",
+    usage: ["CMP NVDA, AMD, AVGO", "CMP TQQQ, QQQ"],
     keys: CHART_KEYS,
     data: QUOTES,
     bloomberg: ["COMP", "TRA"],
@@ -228,14 +237,14 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     summary: "Screen covered stocks on valuation, growth, margins, liquidity, volatility, short interest, insider activity and 13F holders, then rank the matches by any metric. "
       + "ATR% is the 14-session average true range as a percent of the last close. IV rank is a rank, not an IV percentile: 0 is the lowest 30-day implied volatility of the past 52 weeks and 100 the highest.",
     usage: ["EQS"],
-    keys: [key("a", "dd criterion"), key("m", "etric"), key("s", "ave screen"), key("o", "pen research")],
+    keys: [key("a", "dd criterion"), key("m", "etric"), key("t", "check ticker"), key("s", "ave screen"), key("o", "pen research")],
     data: same("Daily snapshot, statements as filed"),
     bloomberg: ["EQS"],
   },
   OMON: {
     summary: "Calls and puts by expiry with bid, ask, spread, volume, open interest, implied volatility, Greeks, extrinsic per year and a put's cost as a percent of spot. "
       + "The Strikes filter lists every strike, a count either side of the money, or a delta band such as .70 to .90 for deep in-the-money LEAPS.",
-    usage: ["OMON NVDA", "gloomberb fn OMON NVDA --expiration 2028-01-21"],
+    usage: ["OMON NVDA", "gloom fn OMON NVDA --expiration 2028-01-21"],
     keys: [key("c", "alc"), key("a", "dd to OSA"), key("s", "urface")],
     data: OPTIONS,
     bloomberg: ["OMON"],
@@ -265,24 +274,33 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
   OSA: {
     summary: "Build a multi-leg options position and value it at any spot, date and vol shift: payoff, P&L grid, breakevens and Greeks. European pricing, so no early exercise. "
       + "With a NAV and a budget in bps it sizes the position as a hedge: contracts, premium, notional protected and coverage of an equity sleeve. "
-      + "--strategy csp sells a cash-secured put: cash secured, premium, yield on cash and annualised, distance out of the money, break-even, days to expiry and an earnings flag.",
-    usage: ["OSA AAPL", "gloomberb fn OSA AAPL --strategy vertical --expiration 2027-01-15",
-      "gloomberb fn OSA KO --strategy csp --strike 85 --expiration 2026-11-20",
-      "gloomberb fn OSA SPY --strategy put --strike 700 --expiration 2027-01-15 --nav 100m --budget-bps 50 --sleeve 100m"],
+      + "--strategy csp sells a cash-secured put: cash secured, premium, yield on cash and annualised, the bid, ask and spread with the yield at the bid, "
+      + "distance out of the money, break-even, days to expiry and an earnings flag. CSP ranks the same put across several names.",
+    usage: ["OSA AAPL", "gloom fn OSA AAPL --strategy vertical --expiration 2027-01-15",
+      "gloom fn OSA KO --strategy csp --strike 85 --expiration 2026-11-20",
+      "gloom fn OSA SPY --strategy put --strike 700 --expiration 2027-01-15 --nav 100m --budget-bps 50 --sleeve 100m"],
     keys: [key("a", "dd leg"), key("c", "hain"), key("d", "ate"), key("v", "ol shift")],
     data: OPTIONS,
     bloomberg: ["OSA"],
   },
+  CSP: {
+    summary: "Which names pay most to sell a put? For each, the put nearest a delta (0.30) on the expiry nearest a date or a number of days out (30), "
+      + "ranked by annualised yield on cash at the bid, with % out of the money, delta, IV rank, the spread (marked wide, never left out) and an earnings flag.",
+    usage: ["CSP JPM, GS, KO", "gloom fn CSP JPM GS KO AAPL --delta 0.20 --days 45"],
+    keys: [key("Enter", " open in OSA")],
+    data: OPTIONS,
+    bloomberg: [],
+  },
   OVDV: {
     summary: "The implied volatility surface fitted from option quotes: 3D sheet, table, smiles, ATM term structure, 25-delta skew and forwards, live or on stored daily closes.",
-    usage: ["OVDV NVDA", "gloomberb fn OVDV NVDA --tab skew --expiration 2027-01-15", "gloomberb fn OVDV SPY --date 2026-10-09 --tab skew"],
+    usage: ["OVDV NVDA", "gloom fn OVDV NVDA --tab skew --expiration 2027-01-15", "gloom fn OVDV SPY --date 2026-10-09 --tab skew"],
     keys: [key("v", "iew"), key("c", "hain"), key("m", "ore expiries"), key("t", " stored dates")],
     data: { free: `${DELAYED}; stored dates at the close`, pro: "Real-time; stored dates at the close" },
     bloomberg: ["OVDV"],
   },
   HIVG: {
     summary: "Daily 30-day, 90-day and one-year at-the-money implied vol since February 2024 against realized vol, with each measure's 52-week rank and percentile.",
-    usage: ["HIVG AAPL", "gloomberb fn HIVG SPY --lookback ALL --csv"],
+    usage: ["HIVG AAPL", "gloom fn HIVG SPY --lookback ALL --csv"],
     keys: [key("s", "urface")],
     data: IV_DAILY,
     bloomberg: ["HIVG", "GV"],
@@ -380,8 +398,8 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["CACS"],
   },
   EVTS: {
-    summary: "The market's report days with implied and past moves; a ticker picks its row.",
-    usage: ["EVTS", "EVTS NVDA"],
+    summary: "The market's report days with implied and past moves, or a past or coming week or day of them; a ticker picks its row.",
+    usage: ["EVTS", "EVTS NVDA", "gloom fn EVTS --week last", "gloom fn EVTS --date 2026-10-15"],
     keys: [key("t", "icker"), key("e", "stimates"), key("c", "alls"), key("a", "nalysts")],
     data: EARNINGS_DAYS,
     bloomberg: ["EVTS"],
@@ -405,7 +423,7 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["DVD"],
   },
   SI: {
-    summary: "FINRA short interest settlements with shares short, days to cover and average daily volume over time. Daily volume is the other tab.",
+    summary: "FINRA short interest settlements with shares short, days to cover and average daily volume over time. Daily volume, fails to deliver and weekly ATS/OTC volume are the other tabs.",
     usage: ["SI AAPL"],
     keys: [key("v", "iew"), STEP],
     data: same("Twice a month, as FINRA publishes"),
@@ -425,6 +443,20 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     data: same("Daily, the evening after each session"),
     bloomberg: [],
   },
+  FTD: {
+    summary: "The short interest pane on Fails to deliver: outstanding fail shares for each settlement date and CUSIP. These snapshots are never added across dates.",
+    usage: ["FTD AAPL"],
+    keys: [key("v", "iew"), OPEN, OPEN_SOURCE],
+    data: same("Twice a month, as the SEC publishes"),
+    bloomberg: [],
+  },
+  ATS: {
+    summary: "The short interest pane on Weekly ATS/OTC: ATS and non-ATS off-exchange shares and trades. ATS % is ATS shares divided by published off-exchange shares, not total market volume or short volume.",
+    usage: ["ATS AAPL"],
+    keys: [key("v", "iew"), OPEN, OPEN_SOURCE],
+    data: same("Weekly with FINRA's publication delay"),
+    bloomberg: [],
+  },
   DIAG: {
     summary: "A read of the company's filings and numbers into red flags, anomalies, green flags and items to watch, each with the evidence it came from.",
     usage: ["DIAG NVDA"],
@@ -458,8 +490,8 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["CF"],
   },
   CALLS: {
-    summary: "Earnings call transcripts with speakers, the analyst Q&A, and extracted guidance and quotes. Alone it lists every transcribed call as it lands.",
-    usage: ["CALLS", "CALLS NVDA"],
+    summary: "Earnings call transcripts with speakers, the analyst Q&A, and extracted guidance and quotes. With a ticker, the company's calls, its next one first with its start and how far away it is. Alone, the calendar of every company's calls this week; --view transcripts lists the latest transcripts.",
+    usage: ["CALLS", "CALLS NVDA", "CALLS --view transcripts"],
     keys: [OPEN, key("/", "find"), OPEN_SOURCE],
     data: pro("Within hours of the call"),
     access: "pro",
@@ -506,9 +538,9 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: [],
   },
   HIRE: {
-    summary: "Pro hiring momentum: weekly observed open roles, additions and removals, role families, seniority, remote and location mix, peers and primary posting evidence. Observed requisitions are not headcount. No argument opens the covered-company board.",
-    usage: ["HIRE", "HIRE NET", "HIRE 0700:HKEX"],
-    keys: [TABS, OPEN, key("e", "vidence"), key("o", "pen source"), key("d", "es"), key("g", "raph")],
+    summary: "Pro hiring momentum: weekly observed open roles, additions and removals, role families, seniority, remote and location mix, peers and primary posting evidence. Moves ranks the companies whose new roles accelerated or slowed against their own weeks and their peers, with why and the postings behind it. Observed requisitions are not headcount. No argument opens the covered-company board.",
+    usage: ["HIRE", "HIRE NET", "HIRE 0700:HKEX", "gloom fn HIRE RIVN --tab moves"],
+    keys: [TABS, OPEN, key("e", "vidence"), key("o", "pen source"), key("d", "es"), key("g", "raph"), key("n", "otify")],
     data: { free: "Latest values and three rows per section", pro: "Weekly history, all stored observations and evidence" },
     access: "preview",
     bloomberg: [],
@@ -658,7 +690,7 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["CN"],
   },
   NI: {
-    summary: "Market news by topic code (MNA, CB, ENERGY, REG, CRYPTO, EARN, IPO) or sector.",
+    summary: "Market news by topic code (MNA, CB, ENERGY, METALS, REG, CRYPTO, EARN, IPO) or sector.",
     usage: ["NI ENERGY"],
     keys: [OPEN, SEARCH, POP_OUT, key("t", "icker")],
     data: NEWS,
@@ -730,7 +762,7 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["IMAP"],
   },
   FXC: {
-    summary: "A cross-rate matrix for the major currencies, or for any of 45 chosen in its settings or with --currencies from the command line (gloomberb fn FXC --currencies USD,ZAR,NGN).",
+    summary: "A cross-rate matrix for the major currencies, or for any of 45 chosen in its settings or with --currencies from the command line (gloom fn FXC --currencies USD,ZAR,NGN).",
     usage: ["FXC"],
     keys: [],
     data: FX,
@@ -751,6 +783,13 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     data: same("Real-time where it streams, others every 15 seconds"),
     bloomberg: [],
   },
+  ETFF: {
+    summary: "Daily net flows of the US spot bitcoin and ether ETFs, fund by fund in US$ millions, with the last 5 and 20 days, the running total since launch, and the funds the newest day still waits on.",
+    usage: ["ETFF", "gloom fn ETFF --asset eth"],
+    keys: [key("1-4", " range"), OPEN_SOURCE],
+    data: same("Daily, as each fund reports after the US close"),
+    bloomberg: [],
+  },
   FUT: {
     summary: "Each root's front futures contract (until its stated roll date) and the day's most active month across equity index, equity sectors, rates, energy, metals, agriculture, livestock and FX with last price, unit and session change, grouped by sector.",
     usage: ["FUT"],
@@ -759,7 +798,7 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["GLCO"],
   },
   CTM: {
-    summary: "A futures root's listed contracts as a curve against a week and a month ago, with roll yield, contango or backwardation, and each contract's price, open interest and volume. Takes a FUT root, VX or a CME crypto root (BTC, ETH, SOL, XRP), which also shows each contract's premium to spot and annualised basis against the USD pair quote: Ann Basis = (Last / spot - 1) × 365 / days to expiry, simple actual/365.",
+    summary: "A futures root's listed contracts as a curve against a week and a month ago, with roll yield, contango or backwardation, and each contract's price, open interest and volume. Takes a FUT root, VX or a CME crypto root (BTC, ETH, SOL, XRP), which also shows each contract's premium to spot and annualised basis against the USD pair in the minute of each contract's last trade: Ann Basis = (Last / spot - 1) × 365 / days to expiry, simple actual/365, with days counted to final settlement.",
     usage: ["CTM GC", "CTM BTC"],
     keys: [key("d", "ate"), key("c", "urrent"), STEP],
     data: same("Delayed, usually 10 minutes; VIX at settlement"),
@@ -986,7 +1025,7 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
   },
   CDS: {
     summary: "Single-name corporate CDS from DTCC public dissemination. CDS alone lists the issuers traded in the last 5 days with trade count, last trade, 5Y spread and its 1W and 1M moves through the roll while the level is current, to rank them by (`fn CDS --sort 1m`); past 2,000bp a name is quoted in points upfront (`57.6 pts`), moves too, and ranks after the bp names; with a ticker or issuer, its 5Y spread (level, date, 1W and 1M change, range), its trades and, in `fn`, its daily levels (`fn CDS F --csv --section daily`).",
-    usage: ["CDS", "CDS F", "gloomberb fn CDS --sort 1m", "gloomberb fn CDS F --csv --section daily"],
+    usage: ["CDS", "CDS F", "gloom fn CDS --sort 1m", "gloom fn CDS F --csv --section daily"],
     keys: [OPEN, STEP],
     data: same("Delayed, as trades are disseminated"),
     bloomberg: ["CDS"],
@@ -1029,7 +1068,7 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["CF"],
   },
   ETF: {
-    summary: "A US-listed fund's SEC filings: registration statements and prospectus updates, shareholder reports, N-CEN and N-PORT reports. Open any of them inline.",
+    summary: "A US-listed fund's facts, a leveraged or inverse fund's daily objective among them, then its own SEC filings: registration statements and prospectus updates, shareholder reports, N-CEN and N-PORT reports. Open any of them inline.",
     usage: ["ETF SPY"],
     keys: [OPEN, OPEN_SOURCE],
     data: AS_FILED,
@@ -1088,7 +1127,7 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
   // Run a workspace
   PF: {
     summary: "Your portfolio or watchlist with live quotes, market value, P&L, weights of the total with cash, and sparklines. With target weights set, each holding adds its target, drift and the trade that rebalances it; broker-synced and manual positions sit in the same table.",
-    usage: ["PF"],
+    usage: ["PF", "PF Family"],
     keys: [key("a", "dd"), OPEN, key("s", " grid")],
     data: QUOTES,
     bloomberg: [],
@@ -1307,7 +1346,7 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: [],
   },
   PL: {
-    summary: "What Gloomberb is made of: switch built-ins on and off, one by one or by applying a starter pack, and install plugins from GitHub.",
+    summary: "What Gloom is made of: switch built-ins on and off, one by one or by applying a starter pack, and install plugins from GitHub.",
     usage: ["PL"],
     keys: [key("e", "nable"), key("a", "pply pack"), key("i", "nstall"), SEARCH],
     data: null,