@gloom-sh/terminal 0.18.5 → 0.19.0

package/src/cli/output-file.ts

@@ -0,0 +1,68 @@
+import { mkdir, stat, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { posix, win32 } from "path";
+
+interface OutputPathContext {
+  cwd?: string;
+  home?: string;
+  platform?: NodeJS.Platform;
+}
+
+/** `C:\Users\me\out.csv`, `C:/out.csv`, `\\server\share\out.csv`: a path only Windows reads. */
+const WINDOWS_PATH = /^(?:[A-Za-z]:[\\/]|\\\\)/;
+
+/**
+ * The absolute path `--output <path>` names, in any form a shell passes it:
+ * relative to the folder the command runs in, absolute, or under the home
+ * folder (`~/Desktop/rv.csv`, which a shell leaves as typed after
+ * `--output=`). A Windows path is read as one on Windows; anywhere else it
+ * is refused, since it would write a file named after the whole path.
+ */
+export function resolveOutputPath(raw: string, context: OutputPathContext = {}): string {
+  const platform = context.platform ?? process.platform;
+  const paths = platform === "win32" ? win32 : posix;
+  const typed = raw.trim();
+  if (!typed) throw new Error("--output needs a file to write, such as --output report.csv.");
+  if (platform !== "win32" && WINDOWS_PATH.test(typed)) {
+    throw new Error(`${typed} is a Windows path. Write a path on this computer, such as --output ~/Desktop/report.csv.`);
+  }
+  const home = context.home ?? homedir();
+  const homeRelative = /^~(?:$|[\\/])/.test(typed);
+  const expanded = homeRelative ? paths.join(home, typed.slice(1)) : typed;
+  return paths.resolve(context.cwd ?? process.cwd(), expanded);
+}
+
+function errorCode(error: unknown): string | undefined {
+  return error && typeof error === "object" && "code" in error ? String((error as { code: unknown }).code) : undefined;
+}
+
+function isFolder(path: string, paths: typeof posix): Error {
+  return new Error(`Cannot write ${path}: it is a folder. Name a file in it, such as ${paths.join(path, "report.csv")}.`);
+}
+
+/** Fails when `path` names a folder: checked before a report loads, so it stops at once. */
+export async function checkOutputPath(path: string, platform: NodeJS.Platform = process.platform): Promise<void> {
+  const existing = await stat(path).catch(() => {
+    // Intentional ignore: a path that does not exist yet is the usual case, and writing reports any real failure.
+    return null;
+  });
+  if (existing?.isDirectory()) throw isFolder(path, platform === "win32" ? win32 : posix);
+}
+
+/**
+ * Writes a command's output to `path`, creating the folders it names as
+ * `shot --output` does, and failing with what to do when it cannot.
+ */
+export async function writeOutputFile(path: string, contents: string, platform: NodeJS.Platform = process.platform): Promise<void> {
+  const paths = platform === "win32" ? win32 : posix;
+  try {
+    await mkdir(paths.dirname(path), { recursive: true });
+    await writeFile(path, contents);
+  } catch (error) {
+    const code = errorCode(error);
+    if (code === "EISDIR") throw isFolder(path, paths);
+    if (code === "EACCES" || code === "EPERM") throw new Error(`Cannot write ${path}: permission denied.`);
+    if (code === "ENOTDIR" || code === "EEXIST") throw new Error(`Cannot write ${path}: a file stands where one of its folders would be.`);
+    throw new Error(`Cannot write ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}

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

@@ -2,6 +2,7 @@ import type {
   HeadlessPaneArgumentDef,
   HeadlessPaneDefinition,
   HeadlessPaneOptionDef,
+  HeadlessPaneReference,
   PaneDef,
   PaneTemplateDef,
 } from "../../types/plugin";
@@ -26,6 +27,8 @@ export interface PaneFunctionCapability {
   screenshotReadiness: PaneFunctionScreenshotReadiness;
   dataRequirements: string[];
   limitations: string[];
+  /** Lists the catalog prints under the options (EQS's sector and industry names). */
+  reference?: HeadlessPaneReference[];
   options: PaneFunctionOptionDef[];
   /** A rendered view that refuses any option it does not declare (PaneDef.reportOptionsOnly), as a headless report does. */
   strictOptions?: boolean;

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/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
@@ -534,6 +549,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 +602,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 } : {}),
@@ -857,6 +876,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 +902,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 +983,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";
@@ -987,7 +1068,9 @@ function statusLineParts(freshness: ReportFreshness, detail: StatusLineDetail =
     ...(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"],

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: {