gloomberb 0.16.1 → 0.16.3

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

@@ -0,0 +1,400 @@
+import type {
+  HeadlessBundleResult,
+  HeadlessFreshnessStatus,
+  HeadlessPaneDefinition,
+  HeadlessPaneFreshness,
+  HeadlessPaneResult,
+  HeadlessPaneRow,
+  HeadlessSeriesResult,
+  HeadlessSnapshotResult,
+} from "../../types/plugin";
+import { formatUtcTime, parseReportTime, type ReportTime } from "../../utils/utc-time";
+import { isRecord } from "../../utils/guards";
+import { latestRegularSessionClose } from "../../market-data/market/freshness";
+
+/**
+ * The four states of docs/usage.md#how-current-a-report-is, plus `unreported`
+ * for a report that cannot tell: a rendered view whose footer names no state,
+ * or a plugin that declares nothing and carries no feed signal.
+ */
+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. */
+  asOf: string | null;
+  /** Oldest observation, when it is more than a day older than `asOf`. */
+  oldest?: string;
+  status: ReportFreshnessStatus;
+  delayMinutes?: number;
+  /** How old the stale data is: the newest observation, or the oldest stale row when only some are. */
+  ageMinutes?: number;
+  /** When only some rows are stale: how many, of the rows that say whether they are... */
+  staleCount?: number;
+  observationCount?: number;
+  /** ...and what the rest are. */
+  feed?: "live" | "delayed";
+  basis?: string;
+  /** When this report was built. */
+  retrievedAt: string;
+}
+
+const DEFAULT_REPORT_SOURCE = "Gloom Cloud";
+
+/** Top-level row and metadata keys that say when a value was observed. */
+const OBSERVATION_KEYS = [
+  "asOf", "asOfDate", "observedAt", "quoteTime",
+  "quoteAsOf", "priceAsOf", "sourceAsOf", "lastTradeTime", "timestamp",
+];
+// Updates can be refresh stamps; use them only when there is no explicit observation.
+const UPDATE_KEYS = ["lastUpdated", "updatedAt"];
+// A stamp a little ahead of this clock is skew; further ahead it is a schedule, not an observation.
+const FUTURE_TOLERANCE_MS = 10 * 60_000;
+const OLDEST_GAP_MS = 24 * 60 * 60_000;
+// A scheduled release can slip by hours; a day past it, the data has missed it.
+const RELEASE_GRACE_MS = 24 * 60 * 60_000;
+
+interface FeedSignals {
+  live: boolean;
+  delayed: boolean;
+  delayMinutes?: number;
+  /** A record-wide stale flag (metadata), read only when no row says whether it is stale. */
+  stale: boolean;
+  /** Rows and series that carry a `stale` flag, and the times of those that are stale. */
+  flagged: number;
+  staleTimes: Array<ReportTime | null>;
+}
+
+interface Observations {
+  /** One time per row, item or series: what `oldest` compares. */
+  units: ReportTime[];
+  /** Metadata and snapshot stamps: candidates for `asOf` only. */
+  extra: ReportTime[];
+}
+
+function emptySignals(): FeedSignals {
+  return { live: false, delayed: false, stale: false, flagged: 0, staleTimes: [] };
+}
+
+function readFeedSignals(record: Record<string, unknown>, signals: FeedSignals): void {
+  if (record.dataSource === "live") signals.live = true;
+  if (record.dataSource === "delayed") signals.delayed = true;
+  const delay = record.delayMinutes;
+  if (typeof delay === "number" && Number.isFinite(delay) && delay > 0) {
+    signals.delayed = true;
+    signals.delayMinutes = Math.max(signals.delayMinutes ?? 0, delay);
+  }
+}
+
+/** A row's or series' own stale flag; worst of across them, counted so a partly stale board says how much. */
+function readUnitStale(record: Record<string, unknown>, time: ReportTime | null, signals: FeedSignals): void {
+  if (typeof record.stale !== "boolean") return;
+  signals.flagged += 1;
+  if (record.stale) signals.staleTimes.push(time);
+}
+
+function observedTime(record: Record<string, unknown>, now: number, keys: readonly string[] = OBSERVATION_KEYS): ReportTime | null {
+  let newest: ReportTime | null = null;
+  for (const key of keys) {
+    const time = parseReportTime(record[key]);
+    if (time && time.time <= now + FUTURE_TOLERANCE_MS && (!newest || time.time > newest.time)) newest = time;
+  }
+  return newest;
+}
+
+function resultRecords(definition: Pick<HeadlessPaneDefinition, "shape">, result: HeadlessPaneResult): HeadlessPaneRow[] {
+  switch (definition.shape) {
+    case "rows":
+      return (result as { rows: HeadlessPaneRow[] }).rows;
+    case "bundle":
+      return (result as HeadlessBundleResult).sections.flatMap((section) => (
+        "rows" in section && section.rows ? section.rows : []
+      ));
+    case "snapshot":
+      return (result as HeadlessSnapshotResult).items;
+    case "series":
+      return [];
+    default: {
+      const _exhaustive: never = definition.shape;
+      return _exhaustive;
+    }
+  }
+}
+
+function seriesNewestTime(series: HeadlessSeriesResult["series"][number], now: number): ReportTime | null {
+  for (let index = series.points.length - 1; index >= 0; index -= 1) {
+    const point = series.points[index]!;
+    if (point.value == null && point.close == null) continue;
+    const time = parseReportTime(point.date);
+    if (time && time.time <= now + FUTURE_TOLERANCE_MS) return time;
+  }
+  return null;
+}
+
+function collect(
+  definition: Pick<HeadlessPaneDefinition, "shape">,
+  result: HeadlessPaneResult,
+  now: number,
+  { observedKey, ignoreStaleFlags }: Pick<HeadlessPaneFreshness, "observedKey" | "ignoreStaleFlags">,
+): { signals: FeedSignals; observations: Observations } {
+  const signals = emptySignals();
+  const observations: Observations = { units: [], extra: [] };
+  const rowKeys = observedKey ? [observedKey] : OBSERVATION_KEYS;
+  for (const row of resultRecords(definition, result)) {
+    if (!isRecord(row)) continue;
+    readFeedSignals(row, signals);
+    const time = observedTime(row, now, rowKeys)
+      ?? (observedKey ? null : observedTime(row, now, UPDATE_KEYS));
+    if (!ignoreStaleFlags) readUnitStale(row, time, signals);
+    if (time) observations.units.push(time);
+  }
+  if (definition.shape === "series") {
+    for (const series of (result as HeadlessSeriesResult).series) {
+      const record = series as unknown as Record<string, unknown>;
+      readFeedSignals(record, signals);
+      const time = seriesNewestTime(series, now);
+      if (!ignoreStaleFlags) readUnitStale(record, time, signals);
+      if (time) observations.units.push(time);
+    }
+  }
+  if (isRecord(result.metadata)) {
+    readFeedSignals(result.metadata, signals);
+    if (result.metadata.stale === true && !ignoreStaleFlags) signals.stale = true;
+    // An explicit summary as-of can be a real observation (CRYP's newest quote).
+    // A summary update stamp must not supersede dated rows.
+    const time = observedKey ? null : observedTime(result.metadata, now)
+      ?? (observations.units.length ? null : observedTime(result.metadata, now, UPDATE_KEYS));
+    if (time) observations.extra.push(time);
+  }
+  if (definition.shape === "snapshot" && !observedKey) {
+    const time = parseReportTime((result as HeadlessSnapshotResult).asOf);
+    if (time && time.time <= now + FUTURE_TOLERANCE_MS) observations.extra.push(time);
+  }
+  return { signals, observations };
+}
+
+function isoTime(time: ReportTime): string {
+  return time.dateOnly ? new Date(time.time).toISOString().slice(0, 10) : new Date(time.time).toISOString();
+}
+
+function newest(times: ReportTime[]): ReportTime | null {
+  return times.reduce<ReportTime | null>((best, time) => (!best || time.time > best.time ? time : best), null);
+}
+
+function oldest(times: ReportTime[]): ReportTime | null {
+  return times.reduce<ReportTime | null>((best, time) => (!best || time.time < best.time ? time : best), null);
+}
+
+/** The declaration with the result's own fields winning over the definition's. */
+function mergeDeclarations(...declarations: Array<HeadlessPaneFreshness | undefined>): HeadlessPaneFreshness {
+  const merged: HeadlessPaneFreshness = {};
+  for (const declaration of declarations) {
+    if (!declaration) continue;
+    for (const [key, value] of Object.entries(declaration)) {
+      if (value !== undefined) (merged as Record<string, unknown>)[key] = value;
+    }
+  }
+  return merged;
+}
+
+const FEED_RANK: Record<"live" | "delayed" | "stale", number> = { live: 0, delayed: 1, stale: 2 };
+
+function worstFeedStatus(statuses: Array<"live" | "delayed" | "stale">): "live" | "delayed" | "stale" | null {
+  return statuses.reduce<"live" | "delayed" | "stale" | null>((worst, status) => (
+    !worst || FEED_RANK[status] > FEED_RANK[worst] ? status : worst
+  ), null);
+}
+
+/** Completed US sessions after the day of `newest`, counted back from `now`, up to `limit`. */
+function sessionsAfter(newest: ReportTime, now: number, limit: number): number {
+  const newestDate = new Date(newest.time).toISOString().slice(0, 10);
+  let count = 0;
+  let cursor = now;
+  while (count < limit) {
+    const close = latestRegularSessionClose("NYSE", cursor);
+    if (!close || close.date <= newestDate) break;
+    count += 1;
+    cursor = close.close - 1;
+  }
+  return count;
+}
+
+/** What the data's declared schedule says about its age, whatever kind of data it is. */
+function overdue(declared: HeadlessPaneFreshness, asOf: ReportTime | null, now: number): boolean {
+  const nextExpected = declared.nextExpectedAt != null ? parseReportTime(declared.nextExpectedAt) : null;
+  if (nextExpected != null && now > nextExpected.time + RELEASE_GRACE_MS) return true;
+  if (!asOf) return false;
+  if (declared.maxAgeMinutes != null && now - asOf.time > declared.maxAgeMinutes * 60_000) return true;
+  return declared.cadence === "daily" && sessionsAfter(asOf, now, 2) > 1;
+}
+
+interface FreshnessInputs {
+  declared: HeadlessPaneFreshness;
+  signals: FeedSignals;
+  observations: Observations;
+  now: number;
+}
+
+function resolveFreshness({ declared, signals, observations, now }: FreshnessInputs): ReportFreshness {
+  const declaredAsOf = observedTime({ asOf: declared.asOf }, now, ["asOf"]);
+  const asOf = declaredAsOf ?? newest([...observations.units, ...observations.extra]);
+  // 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.
+  const oldestTime = declared.oldest != null ? parseReportTime(declared.oldest)
+    : declaredAsOf || declared.oldest === null ? null : oldest(observations.units);
+  const late = overdue(declared, asOf, now);
+
+  let status: ReportFreshnessStatus;
+  let delayMinutes: number | undefined;
+  let staleAt: ReportTime | null = null;
+  let partial: { staleCount: number; observationCount: number; feed?: "live" | "delayed" } | null = null;
+  if (declared.status === "not-a-feed") {
+    // Age alone does not make filed or published data stale. Honor explicit flags,
+    // with row-level flags outranking the metadata summary, or a missed schedule.
+    const staleRows = signals.staleTimes.length;
+    if (late || (signals.flagged > 0 ? staleRows === signals.flagged : signals.stale)) {
+      status = "stale";
+      staleAt = asOf;
+    } else if (staleRows > 0) {
+      status = "stale";
+      partial = { staleCount: staleRows, observationCount: signals.flagged };
+      staleAt = oldest(signals.staleTimes.filter((time): time is ReportTime => time != null));
+    } else {
+      status = "not-a-feed";
+    }
+  } else {
+    const feed = worstFeedStatus([
+      ...(declared.status ? [declared.status] : []),
+      ...(signals.live ? ["live" as const] : []),
+      ...(signals.delayed ? ["delayed" as const] : []),
+    ]);
+    const staleRows = signals.staleTimes.length;
+    // Rows that say whether they are stale outrank a summary flag beside them.
+    const allStale = feed === "stale" || late
+      || (signals.flagged > 0 ? staleRows === signals.flagged : signals.stale);
+    if (allStale) {
+      status = "stale";
+      staleAt = asOf;
+    } else if (staleRows > 0) {
+      status = "stale";
+      partial = {
+        staleCount: staleRows,
+        observationCount: signals.flagged,
+        ...(feed === "live" || feed === "delayed" ? { feed } : {}),
+      };
+      staleAt = oldest(signals.staleTimes.filter((time): time is ReportTime => time != null));
+    } else {
+      status = feed ?? "unreported";
+    }
+    // A partly stale board still says how far its fresh rows are held back.
+    if (status === "delayed" || partial?.feed === "delayed") delayMinutes = declared.delayMinutes ?? signals.delayMinutes;
+  }
+
+  return {
+    source: declared.source?.trim() || DEFAULT_REPORT_SOURCE,
+    asOf: asOf ? isoTime(asOf) : null,
+    ...(asOf && oldestTime && asOf.time - oldestTime.time > OLDEST_GAP_MS ? { oldest: isoTime(oldestTime) } : {}),
+    status,
+    ...(delayMinutes != null && delayMinutes > 0 ? { delayMinutes } : {}),
+    ...(status === "stale" && staleAt ? { ageMinutes: Math.max(0, Math.floor((now - staleAt.time) / 60_000)) } : {}),
+    ...(partial ?? {}),
+    ...(status === "not-a-feed" && declared.basis ? { basis: declared.basis } : {}),
+    retrievedAt: new Date(now).toISOString(),
+  };
+}
+
+/**
+ * Source, as-of and status for a headless report: what the loader declared
+ * (the result's `freshness` over the definition's), the rest read from the
+ * standard signals in the result. Never live unless the data says so.
+ */
+export function deriveHeadlessFreshness(
+  definition: Pick<HeadlessPaneDefinition, "shape" | "freshness">,
+  result: HeadlessPaneResult,
+  now = Date.now(),
+): ReportFreshness {
+  const declared = mergeDeclarations(definition.freshness, result.freshness);
+  const { signals, observations } = collect(definition, result, now, declared);
+  return resolveFreshness({ declared, signals, observations, now });
+}
+
+/**
+ * A rendered view has no structured data: the source is the pane's
+ * declaration, the times are the cells that carry an instant, and the state
+ * is what the pane's own footer says, or not reported.
+ */
+export function deriveRenderedFreshness(
+  declared: HeadlessPaneFreshness | undefined,
+  input: { footerText: string; cellTimes: unknown[] },
+  now = Date.now(),
+): ReportFreshness {
+  const signals = emptySignals();
+  const footer = input.footerText;
+  const delayed = /\b(\d+)\s*(?:m|min|minutes?)\s+delayed\b/i.exec(footer);
+  if (delayed) {
+    signals.delayed = true;
+    signals.delayMinutes = Number(delayed[1]);
+  } else if (/\bdelayed\b/i.test(footer)) {
+    signals.delayed = true;
+  }
+  if (/\bstale\b/i.test(footer)) signals.stale = true;
+  if (/\breal-time\b/i.test(footer)) signals.live = true;
+  const units = input.cellTimes
+    .map((value) => parseReportTime(value))
+    .filter((time): time is ReportTime => time != null && time.time <= now + FUTURE_TOLERANCE_MS);
+  return resolveFreshness({
+    declared: mergeDeclarations(declared),
+    signals,
+    // Rendered rows are often a history (a news list, a filing feed), so only the newest is cited.
+    observations: { units: [], extra: units },
+    now,
+  });
+}
+
+function ageText(minutes: number): string {
+  if (minutes < 120) return `${minutes} min`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 48) return `${hours} hours`;
+  return `${Math.floor(hours / 24)} days`;
+}
+
+function delayedText(minutes: number | undefined): string {
+  return minutes ? `Delayed ${minutes} min` : "Delayed";
+}
+
+function statusText(freshness: ReportFreshness): string {
+  switch (freshness.status) {
+    case "live":
+      return "Live";
+    case "delayed":
+      return delayedText(freshness.delayMinutes);
+    case "stale": {
+      if (freshness.staleCount != null && freshness.observationCount != null) {
+        const rest = freshness.feed === "live" ? "Live" : freshness.feed === "delayed" ? delayedText(freshness.delayMinutes) : null;
+        return `${rest ? `${rest}, ` : ""}${freshness.staleCount} of ${freshness.observationCount} stale`;
+      }
+      return freshness.ageMinutes != null ? `Stale (${ageText(freshness.ageMinutes)} old)` : "Stale";
+    }
+    case "not-a-feed":
+      return freshness.basis ? `Not a live feed (${freshness.basis})` : "Not a live feed";
+    case "unreported":
+      return "Status not reported";
+    default: {
+      const _exhaustive: never = freshness.status;
+      return _exhaustive;
+    }
+  }
+}
+
+/**
+ * The one line every `fn` text report ends with:
+ * `Source: Gloom Cloud | As of 2026-10-09 00:08 UTC | Delayed 10 min`.
+ * Without a dated observation it says when the report was retrieved instead.
+ */
+export function formatFreshnessLine(freshness: ReportFreshness): string {
+  const time = freshness.asOf
+    ? `As of ${formatUtcTime(freshness.asOf)}${freshness.oldest ? ` (oldest ${freshness.oldest.slice(0, 10)})` : ""}`
+    : `Retrieved ${formatUtcTime(freshness.retrievedAt)}`;
+  return [`Source: ${freshness.source}`, time, statusText(freshness)].join(" | ");
+}

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

@@ -81,6 +81,8 @@ const SEARCH = key("/", "search");
 const OPEN_SOURCE = key("o", "pen source");
 const POP_OUT = key("p", "op out");
 const STEP = key("←/→", " step");
+/** THEM and MEMB members: open them in RRG, CORR, SIW or RIPL, or save them as a watchlist. */
+const MEMBERS_MENU = key(".", " open members in, save as watchlist");
 const CHART_KEYS = [key("s", "eries"), key("i", "ndicators"), key("t", "imeframe"), key("f", "ormulas")];
 
 export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
@@ -114,8 +116,8 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["GIP"],
   },
   G: {
-    summary: "Chart any series together: prices, statement lines, valuation multiples, FRED series, indicators and formulas. Series read SYMBOL:field or FRED:series.",
-    usage: ["G", "G NVDA:revenue, NVDA:net_income"],
+    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"],
     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"],
@@ -292,9 +294,9 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["SEAS"],
   },
   RIPL: {
-    summary: "Which of my holdings are tied to a company that reports soon? Customers your holdings name in their filings, and suppliers whose filings name your holdings, with the disclosed revenue share, by report date.",
+    summary: "Which of my holdings are tied to a company that reports soon? Customers your holdings name in their filings, and suppliers whose filings name your holdings, with the disclosed revenue share, by report date. With Pro, the 2 hops tab adds a supplier's supplier or a customer's customer, the company in between and each hop's share.",
     usage: ["RIPL", "RIPL CRUS QRVO"],
-    keys: [key("Enter", " supply chain"), key("e", "arnings")],
+    keys: [TABS, key("Enter", " supply chain, the route on 2 hops"), key("e", "arnings")],
     data: ON_RELEASE,
     bloomberg: [],
   },
@@ -663,14 +665,14 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
   MEMB: {
     summary: "ETF holdings with weights, shares, member returns, daily contributions and index changes. SPX and SPY use IVV holdings.",
     usage: ["MEMB", "MEMB SPY", "MEMB IWM"],
-    keys: [TABS, OPEN],
+    keys: [TABS, OPEN, MEMBERS_MENU],
     data: same("Dated fund holdings and partial delayed member returns. Nasdaq-100 is not covered."),
     bloomberg: ["MEMB", "MRR", "IMOV"],
   },
   THEM: {
     summary: "Curated thematic baskets with equal-weight returns and breadth. Open a theme to see its members, leaders and laggards. The Themes tab of BI.",
     usage: ["THEM", "THEM nuclear"],
-    keys: [TABS, OPEN, key("Esc", "back")],
+    keys: [TABS, OPEN, key("Esc", "back"), MEMBERS_MENU],
     data: same("Updated every 15 minutes"),
     bloomberg: ["IMAP", "custom baskets"],
   },
@@ -696,10 +698,10 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["FXC"],
   },
   PERP: {
-    summary: "Perpetual funding, open interest and premiums across crypto and stock, index, commodity and FX contracts. Per-market History and Evidence. Pro history with a latest-value free preview.",
+    summary: "Perpetual funding, open interest and premiums across venues, for crypto and stock, index, commodity and FX contracts: a board, rankings, one asset across venues, and a market's History and Evidence.",
     usage: ["PERP", "PERP BTC", "PERP TSLA"],
-    keys: [TABS, SEARCH, OPEN_SOURCE, key("a", "lert"), key("e", "vidence"), key("d", "es"), key("f", "a"), key("g", "raph")],
-    data: { free: "Latest market values", pro: "Observed funding, open interest and stored history; source timestamps retained" },
+    keys: [TABS, OPEN, SEARCH, key("e", "vidence"), key("a", "lert")],
+    data: { free: "A fixed preview and any one market's latest values", pro: "Every market, full rankings and stored history; source timestamps retained" },
     bloomberg: [],
   },
   CRYP: {
@@ -717,8 +719,8 @@ 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.",
-    usage: ["CTM GC"],
+    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.",
+    usage: ["CTM GC", "CTM BTC"],
     keys: [key("d", "ate"), key("c", "urrent"), STEP],
     data: same("Delayed, usually 10 minutes; VIX at settlement"),
     bloomberg: ["CTM", "CT"],
@@ -731,8 +733,8 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: [],
   },
   COT: {
-    summary: "CFTC Commitments of Traders: net positioning by trader class, the weekly change, and one- and three-year percentiles. Pass a root like CL to chart it under the front-month price.",
-    usage: ["COT", "COT CL"],
+    summary: "CFTC Commitments of Traders: net positioning by trader class, the weekly change, and one- and three-year percentiles. Pass a root like CL or BTC (also ETH, MBT, MET, SOL, XRP) for one market, charted under its front-month price where there is one.",
+    usage: ["COT", "COT CL", "COT BTC"],
     keys: [key("c", "lass"), key("s", "cope"), SEARCH],
     data: same("Weekly: Tuesday positions, out on Friday"),
     bloomberg: ["COT"],
@@ -809,10 +811,17 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["IPO"],
   },
   MAP: {
-    summary: "Trading venues around the world with open or closed status, local time and time to the next session change.",
-    usage: ["MAP"],
-    keys: [SEARCH, key("+", " zoom in"), key("-", " zoom out")],
-    data: same("Live, from exchange calendars"),
+    summary: "Trading venues around the world with open or closed status, local time and time to the next session change. Layers add ships, chokepoints, ports, pipelines, fields, LNG terminals and airports to the same map, each with a table of what is in view and the companies it links to.",
+    usage: ["MAP", "MAP ships", "MAP energy", "MAP air", "MAP ports"],
+    keys: [SEARCH, OPEN, key("d", "es"), key("+", " zoom in")],
+    data: same("Venues live from exchange calendars; ships live, chokepoints and ports daily, the rest reference data"),
+    bloomberg: [],
+  },
+  CHOKE: {
+    summary: "Daily vessel transits through the main shipping chokepoints charted together, or one of them by name, as series you can mix with anything else in G.",
+    usage: ["CHOKE", "CHOKE SUEZ"],
+    keys: CHART_KEYS,
+    data: same("Daily"),
     bloomberg: [],
   },
 
@@ -953,10 +962,10 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: [],
   },
   HDS: {
-    summary: "Institutional holders as a table (value, shares, change, percent held) or as an ownership treemap.",
-    usage: ["HDS NVDA"],
-    keys: [TABS, key("o", "pen 13F")],
-    data: same("Quarterly, as 13Fs are filed"),
+    summary: "Institutional holders as a table (value, shares, change, percent held) or as an ownership treemap, and the 13D/G tab: 13D and 13G beneficial owners over 5%, activists and passive stakes, with percent of class, its change and each filer's 13F move.",
+    usage: ["HDS NVDA", "HDS CAR"],
+    keys: [TABS, OPEN, key("o", "pen 13F or filing")],
+    data: same("13F quarterly as filed; 13D and 13G as filed"),
     bloomberg: ["HDS"],
   },
   "13F": {
@@ -983,7 +992,7 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
 
   // Run a workspace
   PF: {
-    summary: "Your portfolio or watchlist with live quotes, P&L, weights and sparklines. Broker-synced and manual positions sit in the same table.",
+    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"],
     keys: [key("a", "dd"), OPEN, key("s", " grid")],
     data: QUOTES,