@gloom-sh/terminal 0.18.5 → 0.19.1

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

@@ -79,6 +79,14 @@ function builtInPanePrefixes(paneId: string): string[] {
   return command ? getCommandPrefixes(command) : [];
 }
 
+/**
+ * What a user types for a function, as the catalog lists it and every error names it: a template's
+ * shortcut or id, a pane opened by a built-in command (LAY) by that command's mnemonic, else the pane's id.
+ */
+export function paneFunctionCode(template: PaneTemplateDef | undefined, pane: PaneDef): string {
+  return template?.shortcut?.prefix ?? template?.id ?? builtInPanePrefixes(pane.id)[0] ?? pane.id;
+}
+
 function registerResolverToken(
   lookup: Map<string, PaneTemplateDef | PaneDef>,
   token: string | undefined,
@@ -195,7 +203,8 @@ export function nearFunctionCodes(
   const near = new Map<PaneTemplateDef, string>();
   for (const template of registry.paneTemplates.values()) {
     const prefix = template.shortcut?.prefix;
-    if (!prefix) continue;
+    // An unlisted function is never offered for a typo.
+    if (!prefix || template.listed === false) continue;
     const code = [prefix, ...template.shortcut?.aliases ?? []].find((candidate) => {
       const known = normalizeLookupToken(candidate);
       return (!commandWord || known[0] === wanted[0]) && typoDistance(wanted, known) === 1;
@@ -215,6 +224,7 @@ export function suggestedFunctionCodes(registry: PaneFunctionCatalog, name: stri
   const wanted = normalizeLookupToken(name);
   if (!wanted) return [];
   return [...registry.paneTemplates.values()].flatMap((template) => {
+    if (template.listed === false) return [];
     const pane = registry.panes.get(template.paneId);
     const words = pane ? getHeadlessPaneDefinition(template, pane)?.discovery?.suggestFor ?? [] : [];
     const code = template.shortcut?.prefix;
@@ -277,9 +287,15 @@ async function buildTemplateCatalogEntry(
   };
 }
 
+/**
+ * The functions `gloom catalog` and search list. An unlisted one (`listed:
+ * false`) is left out, and its pane is not listed in its place; `unlisted`
+ * keeps it, for its own help (`fn ATTN --help`).
+ */
 export async function buildPaneCatalogEntries(
   registry: PaneFunctionCatalog,
   context: MarketContext,
+  { unlisted = false }: { unlisted?: boolean } = {},
 ): Promise<PaneCatalogEntry[]> {
   const entries: PaneCatalogEntry[] = [];
   const templatedPaneIds = new Set<string>();
@@ -288,6 +304,7 @@ export async function buildPaneCatalogEntries(
     const pane = registry.panes.get(template.paneId);
     if (!pane) continue;
     templatedPaneIds.add(pane.id);
+    if (template.listed === false && !unlisted) continue;
     entries.push(await buildTemplateCatalogEntry(template, pane, context));
   }
 
@@ -296,7 +313,7 @@ export async function buildPaneCatalogEntries(
     const [shortcut, ...aliases] = builtInPanePrefixes(pane.id);
     const argument = paneFunctionArgument(undefined, pane);
     entries.push({
-      token: shortcut ?? pane.id,
+      token: paneFunctionCode(undefined, pane),
       label: pane.name,
       description: `Open the ${pane.name} pane.`,
       paneId: pane.id,
@@ -333,6 +350,14 @@ const ALL_WORDS_WITH_FLAGS_BAND = 1000;
 const PER_MATCHED_WORD = 100;
 /** Loose matches (no function carries every word) listed before the rest are left to a refined query. */
 const LOOSE_MATCH_LIMIT = 5;
+/** Loose matches a word of the query names (in the function's code, name or aliases) are all listed, up to this many. */
+const LOOSE_NAMED_LIMIT = 8;
+/** A query word found in what the function is called (its code, name or aliases) outweighs one found in its keywords or description. */
+const PER_WORD_IN_NAME = 3;
+/** A query word that begins a function's code (`vol` for VOLS, `fx` for FXC) is the start of typing it. */
+const PER_WORD_STARTING_CODE = 3;
+/** A query word that is one of the function's own keywords (`vol` for the volatility functions, which also say volume's) names it. */
+const PER_WORD_IS_KEYWORD = 3;
 
 function phraseBand(entry: PaneCatalogEntry, phrase: string): number {
   const lower = (values: Array<string | undefined>) => values
@@ -375,6 +400,12 @@ function nameAndDescription(entry: PaneCatalogEntry): string {
   return nameAndDescriptionFields(entry).join(" ");
 }
 
+/** What a function is called: its code, name and aliases, apart from the keywords and description that say what it covers. */
+function identityFields(entry: PaneCatalogEntry): string[] {
+  return [entry.token, entry.label, entry.paneName, entry.shortcut, ...entry.aliases]
+    .filter((value): value is string => !!value).map((value) => value.toLowerCase().replace(/\s+/g, " "));
+}
+
 function flagText(entry: PaneCatalogEntry): string {
   return [
     entry.argKind,
@@ -394,12 +425,14 @@ interface CatalogMatchScore {
   terms: number;
   /** Those found in the function's name, keywords or description. */
   named: number;
+  /** Those found in what the function is called: its code, name or aliases. */
+  called: number;
 }
 
 function scorePaneCatalogEntry(entry: PaneCatalogEntry, query: string): CatalogMatchScore {
   const terms = queryTerms(query);
-  if (terms.length === 0) return { score: 1, terms: 0, named: 0 };
-  const none = { score: 0, terms: terms.length, named: 0 };
+  if (terms.length === 0) return { score: 1, terms: 0, named: 0, called: 0 };
+  const none = { score: 0, terms: terms.length, named: 0, called: 0 };
 
   const exactTokens = [
     entry.token,
@@ -414,6 +447,8 @@ function scorePaneCatalogEntry(entry: PaneCatalogEntry, query: string): CatalogM
   const named = nameAndDescription(entry);
   const flags = flagText(entry);
   const wholeQuery = query.toLowerCase().trim().replace(/\s+/g, " ");
+  const called = identityFields(entry);
+  const codes = [entry.token, entry.shortcut, ...entry.aliases].filter((value): value is string => !!value).map((value) => normalizeLookupToken(value));
 
   let score = containsPhrase(`${named} ${flags}`, wholeQuery) ? 12 : 0;
   // A query that is one of the function's own keywords ("hedge" for OSA) beats one found inside a
@@ -423,9 +458,16 @@ function scorePaneCatalogEntry(entry: PaneCatalogEntry, query: string): CatalogM
   if (keywords.includes(wholeQuery)) score += 4;
   let matchedTerms = 0;
   let matchedNamed = 0;
+  let matchedCalled = 0;
   let matchedFlagKeys = 0;
   for (const term of terms) {
     const normalized = normalizeLookupToken(term);
+    if (called.some((field) => containsPhrase(field, term))) {
+      score += PER_WORD_IN_NAME;
+      matchedCalled += 1;
+    }
+    if (codes.some((code) => normalized.length >= 2 && code.startsWith(normalized))) score += PER_WORD_STARTING_CODE;
+    if (keywords.includes(term)) score += PER_WORD_IS_KEYWORD;
     // A term starts a word: "rate" is found in "rates" but not in "separate", nor "budget" in "budgetBps".
     if (exactTokens.includes(normalized)) {
       score += 8;
@@ -455,12 +497,13 @@ function scorePaneCatalogEntry(entry: PaneCatalogEntry, query: string): CatalogM
   score += Math.round((matchedTerms / terms.length) * 8);
   if (entry.capability.botSafe) score += 2;
   // One word has no phrase to prefer: it keeps the plain term scores.
-  if (terms.length === 1) return { score, terms: 1, named: matchedNamed };
+  if (terms.length === 1) return { score, terms: 1, named: matchedNamed, called: matchedCalled };
   const allWords = matchedNamed === terms.length ? ALL_WORDS_BAND : matchedTerms === terms.length ? ALL_WORDS_WITH_FLAGS_BAND : 0;
   return {
     score: score + matchedTerms * PER_MATCHED_WORD + (phraseBand(entry, wholeQuery) || allWords),
     terms: terms.length,
     named: matchedNamed,
+    called: matchedCalled,
   };
 }
 
@@ -535,8 +578,14 @@ export function selectPaneCatalogMatches(ranked: PaneCatalogEntry[], query: stri
     const shown = every(complete).slice(0, limit);
     return { shown, hidden: ranked.length - shown.length, loose: false };
   }
+  // No function carries every word: the ones a word names come first, the code or name of a function being what a
+  // reader types ("fx vol" is FXC, whose name has fx, and VOLS, whose name has vol), ahead of one that mentions a word
+  // in its keywords ("implied fx" in ADR) or its flags, and however many of the words a weaker match has.
   const named = scored.filter(({ named }) => named > 0);
-  const shown = every(named.length > 0 ? named : scored).slice(0, Math.min(limit, LOOSE_MATCH_LIMIT));
+  const pool = named.length > 0 ? named : scored;
+  const leading = pool.filter((item) => item.called > 0).slice(0, LOOSE_NAMED_LIMIT);
+  const rest = pool.filter((item) => !leading.includes(item)).slice(0, Math.max(0, LOOSE_MATCH_LIMIT - leading.length));
+  const shown = every([...leading, ...rest]).slice(0, limit);
   return { shown, hidden: ranked.length - shown.length, loose: true };
 }
 
@@ -576,7 +625,7 @@ function optionDescription(option: PaneFunctionOptionDef): string {
   const choices = optionChoices(option);
   const parts = [option.description.replace(/\.$/, "")];
   // An enum that also reads other values (a bar size of any length) lists its values as examples.
-  if (choices.join("|").length > MAX_INLINE_CHOICES) parts.push(`${option.normalize ? "Such as" : "One of"} ${choices.join(", ")}`);
+  if (choices.join("|").length > MAX_INLINE_CHOICES) parts.push(`${option.list ? "Each one of" : option.normalize ? "Such as" : "One of"} ${choices.join(", ")}`);
   if (option.defaultValue !== undefined && option.defaultValue !== "") parts.push(`Default ${String(option.defaultValue)}`);
   return `${parts.join(". ")}.`;
 }
@@ -587,6 +636,26 @@ export function limitationSentence(text: string): string {
   return !trimmed || /[.!?]["')\]]*$/.test(trimmed) ? trimmed : `${trimmed}.`;
 }
 
+/**
+ * Names as lines of at most `width`, each name whole and the names apart by
+ * semicolons, since a name may hold a comma (Furnishings, Fixtures & Appliances).
+ */
+function packNames(names: readonly string[], width: number): string[] {
+  const lines: string[] = [];
+  let line = "";
+  names.forEach((name, index) => {
+    const word = index < names.length - 1 ? `${name};` : name;
+    if (line && line.length + 1 + word.length > width) {
+      lines.push(line);
+      line = word;
+    } else {
+      line = line ? `${line} ${word}` : word;
+    }
+  });
+  if (line) lines.push(line);
+  return lines;
+}
+
 function renderCatalogEntry(entry: PaneCatalogEntry): string {
   const width = Math.min(cliTerminalWidth() ?? CATALOG_TEXT_WIDTH, CATALOG_TEXT_WIDTH);
   const capability = entry.capability;
@@ -620,6 +689,10 @@ function renderCatalogEntry(entry: PaneCatalogEntry): string {
     ));
   }
 
+  for (const { title, items } of capability.reference ?? []) {
+    lines.push("", renderSection(title), ...packNames(items, width - 2).map((line) => `  ${line}`));
+  }
+
   lines.push("", renderSection("Examples"));
   if (capability.reportReadiness !== "unsupported") {
     lines.push(...wrapCommandLine(`gloom fn ${invocation}`, width));

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

@@ -12,7 +12,9 @@ import type {
   PluginPersistence,
 } from "../../types/plugin";
 import { createPluginTeamState } from "../../plugins/team-state";
+import { bindPluginContextNamespaces } from "../../plugins/registry/plugin-state";
 import type { MarketContext } from "../types";
+import { createCommandPluginPersistence } from "../saved-copy-persistence";
 import type { PaneFunctionCatalog } from "./catalog";
 
 export interface PaneDiscoveryOptions {
@@ -173,23 +175,41 @@ export async function createPaneCatalog(context: MarketContext, plugins: GloomPl
     brokers,
   });
 
+  // Each plugin's caches save what a command fetches where the app keeps them, so a failed refresh answers from them.
+  const resources = context.persistence?.resources;
+  const persistences: Array<ReturnType<typeof createCommandPluginPersistence>> = [];
+  const commandPersistence = (stateId: string) => {
+    const persistence = createCommandPluginPersistence(resources, `plugin:${stateId}`);
+    persistences.push(persistence);
+    return persistence;
+  };
+
   const destroy = () => {
     let failure: unknown;
     for (const plugin of setupPlugins.splice(0).reverse()) {
       try { plugin.dispose?.(); } catch (error) { failure ??= error; }
     }
+    // A plugin that keeps its persistence past dispose must not reach a store the command closes.
+    for (const persistence of persistences.splice(0)) persistence.release();
     brokers.clear();
     if (context.resolveBroker === resolveBroker) context.resolveBroker = previousResolver;
     if (failure) throw failure;
   };
 
+  const namespaced = (stateId: string) => ({
+    persistence: commandPersistence(stateId),
+    resume: discoveryContext.resume,
+    configState: discoveryContext.configState,
+    teamState: discoveryContext.teamState,
+  });
   try {
     for (const plugin of plugins) {
       for (const pane of plugin.panes ?? []) panes.set(pane.id, pane);
       for (const template of plugin.paneTemplates ?? []) paneTemplates.set(template.id, template);
       if (plugin.setup) {
         setupPlugins.push(plugin);
-        await plugin.setup(discoveryContext);
+        const stateId = plugin.stateId ?? plugin.id;
+        await plugin.setup(bindPluginContextNamespaces({ ...discoveryContext, ...namespaced(stateId) }, namespaced));
       }
     }
   } catch (error) {

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

@@ -1,6 +1,6 @@
 import type { DesktopPaneShotRenderedRow } from "../desktop-pane-shot";
 import { cliStyles, cliTerminalWidth, renderSection, renderTable, wrapText } from "../../utils/cli-output";
-import { formatUtcTime } from "../../utils/utc-time";
+import { formatUtcTime, parseReportTime } from "../../utils/utc-time";
 import type { MarketContext } from "../types";
 import type { PaneFunctionReport } from "./report";
 import type { ResolvedPaneFunction } from "./resolver";
@@ -83,12 +83,22 @@ function domCellKeys(row: DesktopPaneShotRenderedRow): string[] {
   });
 }
 
+const DAY_MS = 86_400_000;
+/** A time of day in what a cell draws: `11:27`, `9am`. */
+const DRAWN_CLOCK = /\d{1,2}:\d{2}|\b\d{1,2}\s?[ap]m\b/i;
+
 /**
  * A pane may shorten a time to fit ("Wed 11:27", "Oct 2"); the report prints
- * the instant behind it with its date and zone instead.
+ * the instant behind it with its date and zone instead. An instant at exactly
+ * 00:00 UTC that the cell draws without a time of day (a filing's date, an
+ * all-day event) is a day, not a midnight: it prints as the date, as a
+ * date-only value does. The CSV and JSON keep the instant.
  */
 function cellText(cell: DesktopPaneShotRenderedRow["cells"][number]): string {
-  return cell.instant ? formatUtcTime(cell.instant) || cell.text : cell.text;
+  if (!cell.instant) return cell.text;
+  const time = parseReportTime(cell.instant);
+  if (time && !time.dateOnly && time.time % DAY_MS === 0 && !DRAWN_CLOCK.test(cell.text)) return formatUtcTime({ ...time, dateOnly: true });
+  return formatUtcTime(cell.instant) || cell.text;
 }
 
 interface DomTable {

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

@@ -11,7 +11,15 @@ import type {
 import { localTimeSuffix, parseReportTime, type ReportTime } from "../../utils/utc-time";
 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 {
+  reportMarketSession,
+  reportVenueMarkets,
+  reportVenueSessionDates,
+  type ReportMarket,
+  type SessionObservation,
+  type VenueMarket,
+  type VenueSessionDate,
+} from "./market-session";
 import { savedCopyShownAt } from "../../data/saved-copies";
 import { releasedText } from "../../utils/release-date";
 
@@ -77,6 +85,13 @@ export interface ReportFreshness {
   tradingDayMarket?: string;
   /** Where the venues of a quote report stand now, from their session calendars. */
   market?: ReportMarket;
+  /**
+   * With a declared `datesEachVenue`, when the rows trade on two or three
+   * markets that do not all stand alike: where each stands and when it opens,
+   * which the status line gives in place of `market` (`LSE opens 08:00 UTC ·
+   * US 13:30 UTC`).
+   */
+  markets?: VenueMarket[];
   /**
    * With a declared `datesEachVenue`, when the rows trade on more than one
    * market: each market's session date, which the status line gives in place
@@ -108,6 +123,8 @@ export interface ReportFreshness {
   ageOnly?: true;
   /** What the newest observation is, said before its time: `newest story Tue 29 Sep 2026 20:17 UTC`. */
   asOfLabel?: string;
+  /** The line says when the report was retrieved after the newest observation's date (`retrieved Wed 28 Oct 2026 19:07 UTC`). */
+  retrievedToo?: true;
   /** 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. */
@@ -534,6 +551,9 @@ function resolveFreshness({ declared, signals, observations, now }: FreshnessInp
   }
   const { market, closeDate, closeMarket } = reportMarketSession(signals.sessions, now);
   const venueSessions = declared.datesEachVenue && !declaredAsOf ? reportVenueSessionDates(signals.sessions, now) : [];
+  // Each market's own state and open, when they are not all one: `LSE opens 08:00 UTC · US 13:30 UTC`.
+  const venueMarkets = declared.datesEachVenue ? reportVenueMarkets(signals.sessions, now) : [];
+  const markets = venueMarkets.length > 0 && !sameMarketText(venueMarkets, now) ? venueMarkets : [];
   // The close wording dates the newest observation, so only when that is what `asOf` is.
   const asOfClose = closeDate && asOf && !declaredAsOf ? closeDate : null;
   const tradingDayMarket = asOfClose ? closeMarket
@@ -584,6 +604,7 @@ function resolveFreshness({ declared, signals, observations, now }: FreshnessInp
     ...(asOfClose ? { asOfClose } : {}),
     ...(tradingDayMarket ? { tradingDayMarket } : {}),
     ...(market ? { market } : {}),
+    ...(markets.length > 0 ? { markets } : {}),
     ...(venueSessions.length > 0 ? { venueSessions } : {}),
     ...(lagDays != null ? { lagDays } : {}),
     ...(observation ? { observation } : {}),
@@ -591,6 +612,7 @@ function resolveFreshness({ declared, signals, observations, now }: FreshnessInp
     ...(oldestAgeMinutes != null ? { oldestAgeMinutes } : {}),
     ...(status === "unreported" && declared.ageOnly ? { ageOnly: true as const } : {}),
     ...(asOfLabel ? { asOfLabel } : {}),
+    ...(asOf && declared.retrievedToo ? { retrievedToo: true as const } : {}),
     ...(note ? { note } : {}),
     ...(noteVariants.length > 0 ? { noteVariants } : {}),
     ...(schedule ? { schedule } : {}),
@@ -857,6 +879,21 @@ function venueSessionsText(sessions: readonly VenueSessionDate[]): string {
   return groups.map(({ markets, date, close }) => `${listText(markets)} ${dayText(date)} ${close ? "close" : "session"}`).join(", ");
 }
 
+/**
+ * An as-of the feed stamped at exactly 00:00:00.000 UTC reads as the day it
+ * names, as a date-only value does: a daily close, a filing's date or a
+ * published report's has no time of day, so `Mon 26 Oct 2026 00:00 UTC` would
+ * claim one. Quotes keep their time, as does anything a feed or a venue's
+ * sessions date, and bars of a size under a day, whose midnight bar opens then.
+ */
+function asOfAsDay(freshness: ReportFreshness, time: ReportTime | null): ReportTime | null {
+  if (!time || time.dateOnly || time.time % DAY_MS !== 0) return time;
+  const feed = freshness.status === "live" || freshness.status === "delayed" || freshness.feed != null;
+  const intradayBars = freshness.basis === "intraday bars";
+  return feed || intradayBars || freshness.market || freshness.sources?.length || freshness.oldestAgeMinutes != null
+    ? time : { ...time, dateOnly: true };
+}
+
 /**
  * The dated as-of: a session close, a UTC time, a date, or when the report was
  * retrieved; with the oldest observation unless `short`, or when the line says
@@ -868,7 +905,7 @@ function asOfText(freshness: ReportFreshness, short: boolean, local: boolean, un
   if (freshness.venueSessions?.length) return venueSessionsText(freshness.venueSessions);
   const market = freshness.tradingDayMarket;
   const period = freshness.periodicity;
-  const time = parseReportTime(freshness.asOf);
+  const time = asOfAsDay(freshness, parseReportTime(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;
@@ -949,6 +986,53 @@ function marketText(market: ReportMarket, now: number, short: boolean, local: bo
   }
 }
 
+/** Whether every market of a mixed report reads the same (`markets closed until Mon`): one line then says it for all. */
+function sameMarketText(markets: readonly VenueMarket[], now: number): boolean {
+  return new Set(markets.map((market) => marketText(market, now, false, false))).size === 1;
+}
+
+/**
+ * Where each market of a report that mixes them stands, one after another:
+ * the open ones first, then those in an extended session, then the closed ones
+ * by when they open. `markets closed · LSE opens 08:00 UTC · US 13:30 UTC`
+ * while all are closed, else each its own (`LSE open · US pre-market, opens
+ * 13:30 UTC`). A time is the regular session's open, as `marketText` says it;
+ * `short` leaves out `markets closed`.
+ */
+function marketsText(markets: readonly VenueMarket[], now: number, short: boolean, local: boolean): string {
+  const opensAt = (market: VenueMarket) => market.reopensAt ? Date.parse(market.reopensAt) : Number.POSITIVE_INFINITY;
+  const rank = (market: VenueMarket) => market.state === "open" ? 0 : market.state === "closed" ? 2 : 1;
+  const ordered = [...markets].sort((left, right) => rank(left) - rank(right) || opensAt(left) - opensAt(right));
+  // `LSE opens 08:00 UTC · US 13:30 UTC`: a verb is said once for the timed opens that follow each other
+  // with it; a week's first trade after a session's open says its own (`reopens 22:00 UTC`).
+  let previousVerb: string | null = null;
+  const parts = ordered.map((market) => {
+    const reopen = reopenText(market, now, local);
+    const verb = market.state === "closed" && reopen?.time ? market.firstTrade ? "reopens" : "opens" : null;
+    const said = (() => {
+      switch (market.state) {
+        case "open":
+          return `${market.market} open`;
+        case "after-hours":
+          return `${market.market} after hours`;
+        case "pre-market":
+          return reopen?.time ? `${market.market} pre-market, opens ${reopen.text}` : `${market.market} pre-market`;
+        case "closed":
+          if (!reopen) return `${market.market} closed`;
+          if (!reopen.time) return `${market.market} closed until ${reopen.text}`;
+          return `${market.market} ${verb === previousVerb ? "" : `${verb} `}${reopen.text}`;
+        default: {
+          const _exhaustive: never = market.state;
+          return _exhaustive;
+        }
+      }
+    })();
+    previousVerb = verb;
+    return said;
+  });
+  return ordered.every((market) => market.state === "closed") && !short ? ["markets closed", ...parts].join(" · ") : parts.join(" · ");
+}
+
 interface StatusLineDetail {
   /** Leave out the oldest observation. */
   asOf?: "short";
@@ -980,14 +1064,19 @@ function statusLineParts(freshness: ReportFreshness, detail: StatusLineDetail =
   const undated = detail.date === "none";
   return [
     ...(freshness.sources?.length ? sourcesAsOfParts(freshness, freshness.sources, undated)
-      : freshness.unreached && !freshness.asOf ? []
+      // Undated, a saved copy is not "retrieved" now: its own part says when it was saved.
+      : (freshness.unreached || freshness.savedAt) && !freshness.asOf ? []
       : [asOfText(freshness, detail.asOf === "short", local, undated)]),
+    // A list dated by its newest filing says when it was read as well.
+    ...(freshness.retrievedToo && freshness.asOf && !freshness.savedAt ? [`retrieved ${timeText(freshness.retrievedAt, local)}`] : []),
     ...(freshness.schedule && detail.schedule !== "none"
       ? [typeof detail.schedule === "number" ? freshness.scheduleVariants?.[detail.schedule] ?? freshness.schedule : freshness.schedule] : []),
     ...(freshness.oldestAgeMinutes != null ? [`oldest ${ageText(freshness.oldestAgeMinutes)}`] : []),
     ...(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)] : []),
+    ...(detail.market === "none" ? []
+      : freshness.markets?.length ? [marketsText(freshness.markets, now, detail.market === "short", local)]
+      : freshness.market ? [marketText(freshness.market, now, detail.market === "short", local)] : []),
     ...(freshness.note && detail.note !== "none" ? [typeof detail.note === "number" ? freshness.noteVariants?.[detail.note] ?? freshness.note : freshness.note] : []),
   ];
 }

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

@@ -234,9 +234,10 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["RV"],
   },
   EQS: {
-    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"],
+    summary: "Screen covered stocks on valuation, growth, margins, liquidity, volatility, technicals, float and ownership, 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. IV percentile, IV30 change in vol points, HV20 and HV rank screen premium to sell. "
+      + "Technical fields read the last completed session: RSI 14, price vs SMA 20, 50 and 200, trading days since a MACD or golden cross and since a new 20-day or 52-week high or low, and Bollinger width percentile (0 is a six-month squeeze). Ideas holds ready technical screens.",
+    usage: ["EQS", "gloom fn EQS --preset golden-cross"],
     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"],
@@ -285,8 +286,10 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
   },
   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"],
+      + "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. "
+      + "--strategy screens covered calls, verticals, iron condors, straddles, strangles and calendars the same way, with the trade, credit or debit, "
+      + "max gain and loss per contract, break-evens, probability of profit, and an income trade's annualised return or a debit trade's reward to risk.",
+    usage: ["CSP JPM, GS, KO", "gloom fn CSP JPM GS KO AAPL --delta 0.20 --days 45", "gloom fn CSP JPM GS KO --strategy iron-condor"],
     keys: [key("Enter", " open in OSA")],
     data: OPTIONS,
     bloomberg: [],
@@ -713,8 +716,8 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
 
   // Watch markets
   MOST: {
-    summary: "Today's top gainers, losers, most active and trending tickers with price, change, volume against average and market cap, and the pre-market and after-hours movers. On Pro, the gaps at the open.",
-    usage: ["MOST"],
+    summary: "Today's top gainers, losers, most active and trending tickers with price, change, volume against average and market cap, and the pre-market and after-hours movers. On Pro, the gaps at the open. Min float keeps the names with at least that many shares in the float.",
+    usage: ["MOST", "gloom fn MOST --list gainers --min-float 10M"],
     keys: [TABS, OPEN],
     data: { free: DELAYED, pro: REAL_TIME },
     bloomberg: ["MOST"],
@@ -902,9 +905,9 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: [],
   },
   FLOW: {
-    summary: "Sweeps, blocks and large premium prints as they hit the tape, with ticker, strike, expiry and premium.",
-    usage: ["FLOW"],
-    keys: [OPEN],
+    summary: "Sweeps, blocks and large premium prints, and the session's net premium tide.",
+    usage: ["FLOW", "FLOW NVDA"],
+    keys: [TABS, OPEN],
     data: pro(REAL_TIME),
     access: "pro",
     bloomberg: ["FLOW"],
@@ -1423,6 +1426,13 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     data: null,
     bloomberg: [],
   },
+  ROADMAP: {
+    summary: "What is being built, what is planned and what shipped, with each item's votes. Pro members vote on what is building or planned, once per item, and can take the vote back.",
+    usage: ["ROADMAP"],
+    keys: [OPEN, key("v", "ote")],
+    data: null,
+    bloomberg: [],
+  },
   HELP: {
     summary: "Help and the function reference. HELP with a function opens its card, F1 opens the focused pane's, and HELP HELP reaches support.",
     usage: ["HELP", "HELP OMON", "HELP HELP"],

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

@@ -42,6 +42,7 @@ import type { ResolvedPaneFunction } from "./resolver";
 import { isRecord } from "../../utils/guards";
 import { splitSymbolWords } from "../symbol-args";
 import { formatUtcTime, localTimeSuffix } from "../../utils/utc-time";
+import { formatCompact } from "../../utils/format";
 import { deriveHeadlessFreshness, formatFreshnessLine, staleRowsText, withSavedCopy, type ReportFreshness } from "./freshness";
 import { DATA_SERVICE_UNREACHABLE_MESSAGE } from "../../utils/network-failure";
 import { accessGateStatus, errorsAccessGate, isProLock, reportGateText } from "./access-gate";
@@ -235,7 +236,12 @@ export function createHeadlessPaneContext(
         command, noun: "a quote", retry: (key) => `gloom ${command} ${argumentWith(key)}`,
       }, { refresh: !!context.refresh });
       if (!read) return null;
-      return { symbol: read.symbol, ...read.exchange ? { exchange: read.exchange } : {}, ...read.name ? { name: read.name } : {} };
+      return {
+        symbol: read.symbol,
+        ...read.exchange ? { exchange: read.exchange } : {},
+        ...read.name ? { name: read.name } : {},
+        ...read.coinNote ? { coinNote: read.coinNote } : {},
+      };
     },
   };
 }
@@ -369,8 +375,8 @@ export function serializeHeadlessPaneResult(
     }
     case "series": {
       const series = result as HeadlessSeriesResult;
-      // `textDecimals` only shapes the text report; JSON keeps every digit and does not carry it.
-      return { ...common, series: series.series.map(({ textDecimals: _text, ...kept }) => kept), ...(series.stats ? { stats: series.stats } : {}) };
+      // `textDecimals` and `textCompact` only shape the text report; JSON keeps every digit and does not carry them.
+      return { ...common, series: series.series.map(({ textDecimals: _decimals, textCompact: _compact, ...kept }) => kept), ...(series.stats ? { stats: series.stats } : {}) };
     }
     case "snapshot": {
       const snapshot = result as HeadlessSnapshotResult;
@@ -380,6 +386,7 @@ export function serializeHeadlessPaneResult(
         asOf: snapshot.asOf,
         columns: serializableColumns(columns),
         items: snapshot.items,
+        ...(snapshot.empty && snapshot.items.length === 0 ? { empty: snapshot.empty } : {}),
       };
     }
     default: {
@@ -495,14 +502,16 @@ function seriesPointExportDate(series: HeadlessSeries, date: SeriesPointDate, da
  * points, multiples and
  * ratios (P/E, EV/EBITDA, one series over another, VIX 3M / VIX) to two
  * decimals, which a ratio under 0.1 trades for three significant digits so it
- * is not flattened to 0.03, and a 0 to 100 score to a tenth of a point. The
- * exports keep every digit. Any other unit prints as loaded, without float
- * noise.
+ * is not flattened to 0.03, and a 0 to 100 score to a tenth of a point. A
+ * company's reported total (`textCompact`) reads as the tables print one:
+ * 63.33B. The exports keep every digit. Any other unit prints as loaded,
+ * without float noise.
  */
 function seriesValue(series: HeadlessSeries, value: number | null): string {
   if (value == null) return "-";
   if (!Number.isFinite(value)) return displayNumber(value);
   if (series.textDecimals != null) return value.toFixed(series.textDecimals);
+  if (series.textCompact) return formatCompact(value);
   const unit = series.unit?.trim().toLowerCase();
   if (unit === "%" || unit === "pp") return value.toFixed(2);
   if (unit === "x" || unit === "ratio") return value !== 0 && Math.abs(value) < 0.1 ? value.toPrecision(3) : value.toFixed(2);
@@ -701,6 +710,7 @@ function emptyReportReason(
   const bundleReason = definition.shape === "bundle" ? (result as HeadlessBundleResult).empty : undefined;
   if (bundleReason) return bundleReason;
   const ownReason = definition.shape === "rows" ? !!(result as HeadlessRowsResult).empty
+    : definition.shape === "snapshot" ? !!(result as HeadlessSnapshotResult).empty
     : definition.shape === "bundle" && (result as HeadlessBundleResult).sections.some((section) => "empty" in section && !!section.empty && !isLockedSection(section));
   const { failed } = splitErrors(result);
   if (ownReason || failed.length) return null;
@@ -909,7 +919,7 @@ export function renderHeadlessPaneText(
     case "snapshot": {
       const snapshot = result as HeadlessSnapshotResult;
       // The closing source line carries the snapshot's as-of, so it is not printed twice.
-      lines.push(renderRows(snapshot.items, undefined, definition.columns));
+      lines.push(renderRows(snapshot.items, undefined, definition.columns, snapshot.empty));
       break;
     }
     default: {