gloomberb 0.18.1 → 0.18.3

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

@@ -1,6 +1,7 @@
 import { ConnectionHealthRegistry } from "../../core/connection-health";
 import type { TickerRepository } from "../../data/ticker-repository";
 import type { AppConfig } from "../../types/config";
+import type { BrokerAdapter } from "../../types/broker";
 import type { DataProvider } from "../../types/data-provider";
 import type { PersistedResourceValue } from "../../types/persistence";
 import type {
@@ -20,6 +21,7 @@ export interface PaneDiscoveryOptions {
   tickerRepository?: TickerRepository;
   panes?: Map<string, PaneDef>;
   paneTemplates?: Map<string, PaneTemplateDef>;
+  brokers?: Map<string, BrokerAdapter>;
 }
 
 /** Throws only if a plugin actually reaches for a dependency discovery has no answer for. */
@@ -43,10 +45,12 @@ export function createPaneDiscoveryContext(options: PaneDiscoveryOptions): Gloom
 } {
   const panes = options.panes ?? new Map<string, PaneDef>();
   const paneTemplates = options.paneTemplates ?? new Map<string, PaneTemplateDef>();
+  const brokers = options.brokers ?? new Map<string, BrokerAdapter>();
   return {
     ...buildDiscoveryContext({
       panes,
       paneTemplates,
+      brokers,
       getConfig: options.getConfig,
       marketData: options.marketData ?? unavailable<DataProvider>("Market data"),
       tickerRepository: options.tickerRepository ?? unavailable<TickerRepository>("The ticker repository"),
@@ -60,6 +64,7 @@ export function createPaneDiscoveryContext(options: PaneDiscoveryOptions): Gloom
 function buildDiscoveryContext({
   panes,
   paneTemplates,
+  brokers,
   getConfig,
   marketData,
   tickerRepository,
@@ -67,6 +72,7 @@ function buildDiscoveryContext({
 }: {
   panes: Map<string, PaneDef>;
   paneTemplates: Map<string, PaneTemplateDef>;
+  brokers: Map<string, BrokerAdapter>;
   getConfig: () => AppConfig;
   marketData: DataProvider;
   tickerRepository: TickerRepository;
@@ -84,7 +90,8 @@ function buildDiscoveryContext({
     registerCommand: () => {},
     registerCommandBarSearchProvider: () => () => {},
     registerColumn: () => {},
-    registerBroker: () => {},
+    registerBroker: (broker) => { brokers.set(broker.id, broker); },
+    getBrokerAdapter: (brokerType) => brokers.get(brokerType) ?? null,
     registerCapability: () => {},
     registerTickerResearchTab: () => {},
     registerShortcut: () => {},
@@ -155,10 +162,15 @@ function buildDiscoveryContext({
 
 export async function createPaneCatalog(context: MarketContext, plugins: GloomPlugin[]): Promise<PaneFunctionCatalog> {
   const setupPlugins: GloomPlugin[] = [];
+  const brokers = new Map<string, BrokerAdapter>();
+  const previousResolver = context.resolveBroker;
+  const resolveBroker = (brokerType: string) => brokers.get(brokerType) ?? null;
+  context.resolveBroker = resolveBroker;
   const { panes, paneTemplates, ...discoveryContext } = createPaneDiscoveryContext({
     getConfig: () => context.config,
     marketData: context.dataProvider,
     tickerRepository: context.store,
+    brokers,
   });
 
   const destroy = () => {
@@ -166,6 +178,8 @@ export async function createPaneCatalog(context: MarketContext, plugins: GloomPl
     for (const plugin of setupPlugins.splice(0).reverse()) {
       try { plugin.dispose?.(); } catch (error) { failure ??= error; }
     }
+    brokers.clear();
+    if (context.resolveBroker === resolveBroker) context.resolveBroker = previousResolver;
     if (failure) throw failure;
   };
 

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

@@ -6,6 +6,8 @@ import type { PaneFunctionReport } from "./report";
 import type { ResolvedPaneFunction } from "./resolver";
 import { collectShotSymbols } from "./data";
 import { lockNoteLines } from "./lock-note";
+import { createHeadlessPaneContext } from "./headless";
+import type { HeadlessPaneContext } from "../../types/headless";
 import { lockNoteReason } from "../../plugins/builtin/shared/pro-lock-note";
 import { renderDesktopShot, type PaneScreenshotResult } from "./screenshot";
 import { deriveRenderedFreshness, formatFreshnessLine, type ReportFreshness } from "./freshness";
@@ -204,10 +206,12 @@ function reportRows(result: PaneScreenshotResult): DesktopPaneShotRenderedRow[]
   }];
 }
 
-export function buildDomPaneReportFromRender(
+export async function buildDomPaneReportFromRender(
   resolved: ResolvedPaneFunction,
   result: PaneScreenshotResult,
-): PaneFunctionReport {
+  /** Reads data for the lock note, which names a free route only when it has data for the symbol. */
+  context?: HeadlessPaneContext,
+): Promise<PaneFunctionReport> {
   const rows = reportRows(result);
   const hasStructuredRows = (result.render.reportRows ?? result.render.rows).length > 0;
   // A table that reported every row is whole, whatever the viewport cut from the capture.
@@ -218,7 +222,8 @@ export function buildDomPaneReportFromRender(
   const truncated = truncationReasons.length > 0
     || (result.render.reportTruncationReasons ? false : result.render.truncated);
   const failureReason = renderedFailureReason(result, rows);
-  const unavailableSymbols = failureReason && result.symbols.length > 0 ? result.symbols : [];
+  // A pane that drew rows beside an error or empty marker ("Quote unavailable.") has data: only one with none has no data for its symbols.
+  const unavailableSymbols = failureReason && rows.length === 0 && result.symbols.length > 0 ? result.symbols : [];
   // What the view leaves out and how to see more, such as OMON's strikes outside its window.
   const rendered = renderedReportNotices(result.render.semanticUi ?? []);
   const notices = [...(resolved.pane.reportNotices?.(resolved.instance.settings ?? {}) ?? []), ...rendered.notices];
@@ -227,11 +232,12 @@ export function buildDomPaneReportFromRender(
   // what is locked and how to reach it, and cites no source.
   const gate = !hasStructuredRows ? result.render.accessGate ?? null : null;
   const lockNote = gate
-    ? resolved.pane.reportLockNote?.({
+    ? await resolved.pane.reportLockNote?.({
       gate,
       symbol: result.symbols[0] ?? null,
       token: resolved.token,
       ...gate === "sign-in" && asksToVerifyEmail(result.render.visibleText ?? "") ? { verifyEmail: true } : {},
+      ...context ? { context } : {},
     }) ?? null
     : null;
   const locked = gate === "sign-in" || lockNote ? gate : null;
@@ -399,7 +405,7 @@ export async function buildDomFunctionReport(
   const failure = renderedReportFailure(result.render.semanticUi ?? []);
   if (failure) throw new RenderedReportFailure(failure.message, failure.details);
   try {
-    return buildDomPaneReportFromRender(resolved, result);
+    return await buildDomPaneReportFromRender(resolved, result, createHeadlessPaneContext(resolved, context, new AbortController().signal));
   } catch (error) {
     return failedDomReport(resolved, rawArg, error);
   }

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

@@ -43,7 +43,7 @@ export interface ReportFreshness {
   feed?: "live" | "delayed";
   basis?: string;
   /** Set when the dates are the start of a period: the status line then reads `Sep 2026 (monthly)`. */
-  periodicity?: "monthly" | "quarterly" | "annual";
+  periodicity?: "monthly" | "quarterly" | "semiannual" | "annual";
   /**
    * The newest bar's week or month had not ended, and the last day it covers
    * so far (`asOf`, when known): the status line reads `month to date, through
@@ -335,7 +335,7 @@ function datasetLagDays(observed: ReportTime, periodicity: ReportFreshness["peri
   const month = day.getUTCMonth();
   const through = !periodicity ? Date.UTC(year, month, day.getUTCDate())
     // Day 0 of the month after the period is its last day.
-    : periodicity === "monthly" ? Date.UTC(year, month + 1, 0)
+    : periodicity === "monthly" || periodicity === "semiannual" ? Date.UTC(year, month + 1, 0)
       : periodicity === "quarterly" ? Date.UTC(year, month - (month % 3) + 3, 0)
         : Date.UTC(year, 12, 0);
   const today = new Date(now);
@@ -589,13 +589,13 @@ function tradingDayText(date: string, market: string | undefined): string {
   return market ? `${market} trading day ${dayText(date)}` : dayText(date);
 }
 
-/** `Sep 2026`, `Q2 2026` or `2026` for the period a date starts. */
+/** `Sep 2026`, `Q2 2026` or `2026` for the period a date starts; a semiannual estimate's month. */
 function periodText(date: string, periodicity: NonNullable<ReportFreshness["periodicity"]>): string {
   const day = new Date(`${date.slice(0, 10)}T00:00:00Z`);
   if (!Number.isFinite(day.getTime())) return date;
   const year = day.getUTCFullYear();
   const month = day.getUTCMonth();
-  return periodicity === "monthly" ? `${MONTHS[month]} ${year}`
+  return periodicity === "monthly" || periodicity === "semiannual" ? `${MONTHS[month]} ${year}`
     : periodicity === "quarterly" ? `Q${Math.floor(month / 3) + 1} ${year}`
       : `${year}`;
 }

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

@@ -93,7 +93,7 @@ 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")];
+const CHART_KEYS = [key("s", "eries"), key("i", "ndicators"), key("b", "ars"), key("f", "ormulas")];
 
 export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
   // Research companies
@@ -971,7 +971,7 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: [],
   },
   PDLR: {
-    summary: "Weekly primary dealer net positions and settlement fails across Treasuries and mortgage-backed securities.",
+    summary: "Weekly primary dealer net positions with history, by sector and Treasury tenor (bills, coupons, TIPS, FRN), and settlement fails.",
     usage: ["PDLR"],
     keys: [TABS],
     data: same("Weekly, as published"),
@@ -1110,7 +1110,7 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     docs: "PORT",
   },
   ALRT: {
-    summary: "Your price alerts with current price, distance to target and trigger state, plus alerts days before earnings, CPI or FOMC and market and filing event alerts.",
+    summary: "Your price alerts with current price, distance to target and trigger state, plus alerts on earnings, CPI and FOMC dates, filings and 13F, news keywords, analyst changes, 52-week highs and lows, unusual volume, short interest, insider and congress trades, catalysts, IV spikes, options flow and perps.",
     usage: ["ALRT"],
     keys: [key("a", "dd alert"), key("e", "dit"), key("d", "elete"), key("m", "re-arm")],
     data: QUOTES,
@@ -1238,6 +1238,30 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     data: null,
     bloomberg: [],
   },
+  BUY: {
+    summary: "Open the shared Trade ticket with a buy quantity and optional limit price. Focus starts on Review; choose an account and review the broker preview before confirming.",
+    usage: ["BUY AAPL 10", "BUY AAPL 10 150.25"],
+    keys: [key("r", "eview"), key("o", "rders")],
+    data: same("Broker account and quote"),
+    bloomberg: [],
+    docs: "BR",
+  },
+  SELL: {
+    summary: "Open the shared Trade ticket with a sell quantity and optional limit price. Focus starts on Review; holdings and broker capabilities are checked before confirmation.",
+    usage: ["SELL AAPL 10", "SELL AAPL 10 350.25"],
+    keys: [key("r", "eview"), key("o", "rders")],
+    data: same("Broker account and quote"),
+    bloomberg: [],
+    docs: "BR",
+  },
+  ORD: {
+    summary: "Open orders and recent activity for a selected broker profile and account. Review a modification or confirm cancellation from an open order; uncertain outcomes require reconciliation before another action.",
+    usage: ["ORD"],
+    keys: [key("m", "odify"), key("c", "ancel")],
+    data: same("Broker account snapshot"),
+    bloomberg: [],
+    docs: "BR",
+  },
 
   // Layouts and settings
   GL: {

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

@@ -89,17 +89,36 @@ function normalizeSymbolList(value: string): string[] {
   return symbols;
 }
 
-function validateSymbolCount(
+const COUNT_WORDS = ["zero", "one", "two", "three", "four", "five"];
+const EXAMPLE_TICKERS = ["SPY", "QQQ", "IWM", "DIA", "TLT"];
+
+/**
+ * What a function that compares several tickers answers fewer: how many it
+ * needs and a command that runs, the reader's own tickers first (`CMP needs
+ * two or more tickers: fn CMP SPY,QQQ`).
+ */
+function tooFewTickersMessage(token: string, minimum: number, given: readonly string[], command: "fn" | "shot" = "fn"): string {
+  const example = [...given, ...EXAMPLE_TICKERS.filter((ticker) => !given.includes(ticker))].slice(0, Math.max(minimum, given.length + 1));
+  return `${token} needs ${COUNT_WORDS[minimum] ?? minimum} or more tickers: ${command} ${token} ${example.join(",")}`;
+}
+
+/** The tickers a function's argument lists, as its report reads them. */
+export function argumentSymbols(rawArgument: string): string[] {
+  return normalizeSymbolList(rawArgument);
+}
+
+export function validateSymbolCount(
   definition: HeadlessPaneDefinition,
   token: string,
   symbols: string[],
+  command: "fn" | "shot" = "fn",
 ): void {
   const minimum = definition.argument.minimum
     ?? (definition.argument.optional ? 0 : 1);
   const maximum = definition.argument.maximum;
   if (symbols.length < minimum) {
     if (minimum <= 1) throw requiredArgumentError(definition, token);
-    throw new Error(`${token} requires at least ${minimum} symbols.`);
+    throw new Error(tooFewTickersMessage(token, minimum, symbols, command));
   }
   if (maximum != null && symbols.length > maximum) {
     throw new Error(`${token} accepts at most ${maximum} symbols.`);
@@ -168,12 +187,12 @@ async function loadHeadlessPaneModel(
   return result;
 }
 
-type HeadlessMarketContext = Pick<MarketContext, "config" | "store" | "refresh"> & Partial<Pick<MarketContext, "persistence" | "seriesCapabilities">> & {
+type HeadlessMarketContext = Pick<MarketContext, "config" | "store" | "refresh" | "resolveBroker"> & Partial<Pick<MarketContext, "persistence" | "seriesCapabilities">> & {
   dataProvider: HeadlessPaneContext["marketData"];
 };
 
 /** What a headless loader reads the market, the account and the saved collections through. */
-function createHeadlessPaneContext(
+export function createHeadlessPaneContext(
   resolved: ResolvedPaneFunction,
   context: HeadlessMarketContext,
   signal: AbortSignal,
@@ -186,6 +205,7 @@ function createHeadlessPaneContext(
     ...(context.refresh ? { refresh: true } : {}),
     settings: resolved.instance.settings,
     capabilities: getSharedRegistry() ?? context.seriesCapabilities,
+    resolveBroker: context.resolveBroker,
     async resolvePortfolio(id) {
       const portfolio = findNamedCollection(context.config.portfolios, id);
       if (!portfolio) return null;
@@ -498,7 +518,7 @@ function renderRows(
   };
   return renderTable(
     columns.map((column) => ({
-      header: displayedHeader(column),
+      header: column.textHeader ?? displayedHeader(column),
       align: column.align,
       width: column.width,
       shrink: column.shrink,
@@ -734,14 +754,14 @@ export function headlessReportTables(
       const rowsResult = result as HeadlessRowsResult;
       const columns = displayedColumns(columnsFor(rowsResult.rows, rowsResult.columns, definition.columns));
       const rowIdentities = rowIdentitiesOf(rowsResult.rows, rowsResult);
-      const own = exportRowsTable(title, columns, rowsResult.rows);
+      const own = exportRowsTable(title, columns, rowsResult.rows, { status: true });
       const interval = rowsResult.interval?.trim();
       tables = [{ ...own, ...(rowIdentities ? { rowIdentities } : {}), ...(interval ? { identity: { interval } } : {}) }, ...(rowsResult.exportTables ?? []).map((extra) => {
         const identity = {
           ...(extra.unit?.trim() ? { currencyOrUnit: extra.unit.trim() } : {}),
           ...(extra.interval?.trim() ? { interval: extra.interval.trim() } : {}),
         };
-        const table = exportRowsTable(extra.title, displayedColumns(extra.columns), extra.rows);
+        const table = exportRowsTable(extra.title, displayedColumns(extra.columns), extra.rows, { status: true });
         return Object.keys(identity).length > 0 ? { ...table, identity } : table;
       })];
       break;
@@ -757,7 +777,7 @@ export function headlessReportTables(
           const entries = exportEntriesTable(section.title, section.entries);
           return Object.keys(named).length > 0 ? { ...entries, identity: named } : entries;
         }
-        const table = exportRowsTable(section.title, displayedColumns(columnsFor(section.rows, section.columns, definition.columns)), section.rows);
+        const table = exportRowsTable(section.title, displayedColumns(columnsFor(section.rows, section.columns, definition.columns)), section.rows, { status: true });
         const identity = {
           ...named,
           ...(section.unit?.trim() ? { currencyOrUnit: section.unit.trim() } : {}),
@@ -775,7 +795,7 @@ export function headlessReportTables(
     }
     case "snapshot": {
       const snapshot = result as HeadlessSnapshotResult;
-      tables = [exportRowsTable(title, displayedColumns(columnsFor(snapshot.items, undefined, definition.columns)), snapshot.items)];
+      tables = [exportRowsTable(title, displayedColumns(columnsFor(snapshot.items, undefined, definition.columns)), snapshot.items, { status: true })];
       break;
     }
     default: {
@@ -939,9 +959,9 @@ export async function buildHeadlessFunctionReport(
     loaded = await loadResolvedHeadlessPaneModel(resolved, context, rawArgument);
   } catch (error) {
     // A Pro pane the server refused reports what its wall covers, as its rendered view does.
-    const locked = lockedHeadlessReport(resolved, error, () => (
+    const locked = await lockedHeadlessReport(resolved, error, () => (
       buildHeadlessPaneLoadArgs(resolved.headless!, resolved.token, rawArgument, resolved.options).symbols
-    ));
+    ), createHeadlessPaneContext(resolved, context, new AbortController().signal));
     if (locked) return locked;
     throw error;
   }

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

@@ -36,9 +36,9 @@ import {
 import { isNotATickerMessage } from "../not-a-ticker";
 import { isCliFailure } from "../errors";
 import { isTickerLinkPeer } from "../../layout/ticker-navigation";
-import { knownGapMessage, commandPointer, topicPointer } from "../known-gaps";
-import { selectReportTables } from "../report-tables";
-import { cliOutputWritten } from "../result";
+import { knownGapMessage, commandPointer, commandPointerLeads, topicPointer } from "../known-gaps";
+import { selectReportTables, type CliReportTables } from "../report-tables";
+import { cliOutputWritten, type CliErrorObject } from "../result";
 import type { CatalogCommandHit } from "../unknown-command";
 import { CLI_EXIT_CODES } from "../exit-codes";
 import { shotOptionRefusal } from "./shot-options";
@@ -204,6 +204,63 @@ function foundNothing(data: { rowCount: number; unavailableSymbols: readonly str
   return data.rowCount === 0 || data.unavailableSymbols.length >= data.rowCount;
 }
 
+/** A listing key as asked or reported (`BHP:XASX`, `fred:DGS10`, `SPY`), in one case. */
+const listingKey = (symbol: string) => symbol.trim().toUpperCase();
+const bareKey = (key: string) => key.split(":")[0]!;
+
+/**
+ * The listings asked that a report has no data for. A report names one by its
+ * full key; one that names it by the bare symbol (`SAN` for `SAN:EPA`), or by
+ * the listing a bare symbol resolved to (`SXR8:XETRA` for `SXR8`), stands for
+ * the one listing asked that way, never for a listing asked by its own key:
+ * with `BHP:XASX` and `BHP` asked, `BHP:XASX` unavailable leaves `BHP`.
+ */
+function missingListings(asked: readonly string[], unavailable: readonly string[]): Set<string> {
+  const keys = asked.map(listingKey);
+  const exact = new Set(keys);
+  const missing = new Set<string>();
+  for (const entry of unavailable.map(listingKey)) {
+    if (exact.has(entry)) {
+      missing.add(entry);
+      continue;
+    }
+    const loose = keys.filter((key) => bareKey(key) === bareKey(entry) && key.includes(":") !== entry.includes(":"));
+    if (loose.length === 1) missing.add(loose[0]!);
+  }
+  return missing;
+}
+
+/** Whether a table holds a value past its first column (a row's label or date) and its reasons: a figure, a time, any text. */
+function tablesHoldValues(tables: CliReportTables): boolean {
+  return tables.tables.some((table) => {
+    const skipped = new Set(table.columns.flatMap((header, index) => index === 0 || header === "status" || header === "value_status" ? [index] : []));
+    return table.rows.some((row) => row.some((cell, index) => !skipped.has(index) && cell !== "" && cell != null));
+  });
+}
+
+/**
+ * Why `fn` fails a report it printed, or null when the report has data. It
+ * fails when it is empty (a pane behind a wall reads nothing), when it has no
+ * data for any listing asked and its tables hold no value either, or when it
+ * is a list (`failsWithoutData`) with no name that has any. A report with data
+ * for some of what was asked, warnings or errors beside it, is a result: a
+ * loss-maker's P/E band without a P/E, or IV history with only realized
+ * volatility, exits 0.
+ */
+export function reportFailure(
+  data: { empty: boolean; rowCount: number; symbols: readonly string[]; unavailableSymbols: readonly string[]; errors?: readonly string[]; reason?: unknown },
+  asked: string,
+  { failsWithoutData = false, tables }: { failsWithoutData?: boolean; tables?: CliReportTables } = {},
+): CliErrorObject | null {
+  const missing = missingListings(data.symbols, data.unavailableSymbols);
+  const noListing = data.symbols.length > 0 && data.symbols.every((symbol) => missing.has(listingKey(symbol)));
+  const noValues = tables ? !tablesHoldValues(tables) : false;
+  if (!data.empty && !(noListing && noValues) && !(failsWithoutData && foundNothing(data))) return null;
+  const reasons = [...data.errors ?? [], ...typeof data.reason === "string" ? [data.reason] : []];
+  const unavailable = data.unavailableSymbols.length > 0 ? `no data for ${data.unavailableSymbols.join(", ")}` : "no data";
+  return { code: "no_data", message: `${asked}: ${reasons.length > 0 ? reasons.join("; ") : unavailable}.`.replace(/\.\.$/, ".") };
+}
+
 export async function runPaneFunction(args: string[], ctx: CliCommandContext) {
   await runPaneCliCommand(ctx, async () => {
     await withPaneRuntime(ctx, args, async ({ parsed, context, registry, resolved }) => {
@@ -277,13 +334,15 @@ export async function runPaneFunction(args: string[], ctx: CliCommandContext) {
         ? { ...report.data, glossary: glossary.map(({ term, short, definition }) => ({ term, ...(short ? { short } : {}), definition })) }
         : report.data;
       const warnings = [...parsed.listingNotes ?? [], ...await choice ?? [], ...report.data.warnings ?? []];
+      // A report with no data is printed as it is, and fails: exit 1, and `ok: false` in JSON with the reason.
+      const failure = reportFailure(report.data, ["fn", resolved.token, parsed.arg.trim()].filter(Boolean).join(" "), {
+        failsWithoutData: resolved.headless?.failsWithoutData, tables: report.tables });
       // The report states its own freshness in its data and text; JSON cites it as `source` too.
-      ctx.printResult({ data, exportFreshness: report.data.freshness, ...(warnings.length > 0 ? { warnings } : {}) }, {
+      ctx.printResult({ data, exportFreshness: report.data.freshness, ...(warnings.length > 0 ? { warnings } : {}), ...(failure ? { failure } : {}) }, {
         text: () => glossary ? `${report.text}\n\n${renderReportGlossary(resolved.token, glossary)}` : report.text,
         ...(tabular ? { tables: selectReportTables(report.tables, resolved.tableSection) } : {}),
       });
-      // The report is printed as it is; a list that found data for none of its names says so in the exit status too.
-      if (resolved.headless?.failsWithoutData && foundNothing(report.data)) process.exitCode = CLI_EXIT_CODES.error;
+      if (failure) process.exitCode = CLI_EXIT_CODES.error;
     }, { strictHeadlessOptions: true, tableSection: true });
   });
 }
@@ -486,6 +545,7 @@ export async function runPaneCatalog(args: string[], ctx: CliCommandContext) {
         // A setting or a report can be a command, not a function: "light theme" names `config themes` beside THEM,
         // "drip" names `portfolio show --drip` beside DVD.
         const setting = commandPointer(parsed.query);
+        const settingLeads = commandPointerLeads(parsed.query);
         // The data catalog series the query names, which `fn G` charts.
         const series = findCatalogSeries(ctx.plugins, parsed.query);
         const listed = pointer
@@ -496,7 +556,7 @@ export async function runPaneCatalog(args: string[], ctx: CliCommandContext) {
           ...series.length ? { metadata: { series } } : {},
           ...(gap || setting) && ctx.cliOptions.format !== "text" ? { warnings: [gap, setting].filter((note): note is string => !!note) } : {},
         }, {
-          text: () => renderPaneCatalogReport(filtered, effectiveParsed, glossary, gap, series, setting),
+          text: () => renderPaneCatalogReport(filtered, effectiveParsed, glossary, gap, series, setting, settingLeads),
         });
       } finally {
         registry.destroy();

package/src/cli/pane-functions/lock-note.ts

@@ -2,6 +2,7 @@ import { refusedLock } from "../../plugins/builtin/shared/cloud-denied";
 import { lockNoteReason } from "../../plugins/builtin/shared/pro-lock-note";
 import { cliTerminalWidth, wrapText } from "../../utils/cli-output";
 import { reportFooterLines } from "../report-tables";
+import type { HeadlessPaneContext } from "../../types/headless";
 import type { PaneFunctionReport } from "./report";
 import type { ResolvedPaneFunction } from "./resolver";
 
@@ -22,19 +23,21 @@ export function lockNoteLines(note: string): string[] {
  * `reportLockNote`, no source line and `locked` in JSON. The refusal may be
  * the error itself or the cause of the one a headless read wrote for it
  * (`explainRefusal`). Null when the error is no such refusal or the pane has
- * no note, and the error stands.
+ * no note, and the error stands. The context lets the note check the free
+ * route it names.
  */
-export function lockedHeadlessReport(
+export async function lockedHeadlessReport(
   resolved: ResolvedPaneFunction,
   error: unknown,
   /** The symbols the report was asked for, read once the error is known to be a refusal. */
   symbolsOf: () => string[],
-): PaneFunctionReport | null {
+  context?: HeadlessPaneContext,
+): Promise<PaneFunctionReport | null> {
   const refused = refusedLock(error);
   if (!refused || !resolved.pane.reportLockNote) return null;
   const gate = refused.gate;
   const symbols = symbolsOf();
-  const note = resolved.pane.reportLockNote({ ...refused, symbol: symbols[0] ?? null, token: resolved.token });
+  const note = await resolved.pane.reportLockNote({ ...refused, symbol: symbols[0] ?? null, token: resolved.token, ...context ? { context } : {} });
   const reason = lockNoteReason(note);
   return {
     data: {

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

@@ -23,7 +23,9 @@ import type { MarketContext } from "../types";
 import {
   buildPaneFunctionLookup,
   buildTemplateContext,
+  findFunctionCode,
   nearFunctionCodes,
+  suggestedFunctionCodes,
   suggestPaneFunctions,
   type NearFunctionCode,
   type PaneFunctionCatalog,
@@ -36,6 +38,7 @@ import {
   optionSettings,
   type ParsedPaneFunctionArgs,
 } from "./options";
+import { argumentSymbols, validateSymbolCount } from "./headless";
 import {
   capabilityHasOption,
   capabilityPaneSettings,
@@ -65,9 +68,10 @@ export interface ResolvedPaneFunction {
 }
 
 async function buildPaneInstance(
-  resolved: Pick<ResolvedPaneFunction, "pane" | "template" | "headless" | "createOptions" | "optionSettings" | "capability" | "options">,
+  resolved: Pick<ResolvedPaneFunction, "token" | "pane" | "template" | "headless" | "createOptions" | "optionSettings" | "capability" | "options">,
   context: MarketContext,
   target: string,
+  command: "fn" | "shot",
 ): Promise<PaneInstanceConfig> {
   // Free text is a phrase, not a symbol. Treating it as a ticker makes the
   // pane look for a provider for values such as "HIGH GROWTH SOFTWARE".
@@ -88,7 +92,11 @@ async function buildPaneInstance(
       return { ...spec.settings, ...resolved.optionSettings };
     }
     const chartSpec = parseChartSpec(spec.settings?.chartSpec);
-    if (!chartSpec) throw new Error("The chart template did not produce a valid chart specification.");
+    if (!chartSpec) {
+      // A chart of too few tickers (CMP of one) has none to draw: say how many it takes.
+      if (resolved.headless) validateSymbolCount(resolved.headless, resolved.token, argumentSymbols(target), command);
+      throw new Error("The chart template did not produce a valid chart specification.");
+    }
     return {
       ...spec.settings,
       chartSpec: applyChartComposerCapabilityOptions(
@@ -148,7 +156,8 @@ export async function applyListingArgument(
   // A list entry with spaces is a company's name search finds, or the symbols it holds.
   const typed = takesOneTicker ? [args.arg] : await readNameEntries(splitSymbolArgs([args.arg]), context.dataProvider);
   if (typed.length === 0) return args;
-  let listings = await Promise.all(typed.map((raw) => resolveCliListing(raw, exchange, context, { ownExchangeWins: typed.length > 1 })));
+  // RY.TO is the listing its quote names, RY:TSX, as `quote` reads it: a function's data is read by venue.
+  let listings = await Promise.all(typed.map((raw) => resolveCliListing(raw, exchange, context, { ownExchangeWins: typed.length > 1, venueSuffix: true })));
   // A separator stuck to the end of a pasted list (`UPST;`) is not part of a symbol; it is named.
   const notes: string[] = takesOneTicker ? [] : stripStrayEdges(args.arg).notes;
   const token = found.template?.shortcut?.prefix ?? args.target.toUpperCase();
@@ -242,15 +251,21 @@ async function unknownPaneFunctionError(
   // NIM is one slip from NI, but a bank figure is in `fundamentals`, not in a function's statement lines.
   const bank = bankFigurePointer(name, arg);
   if (bank) return new UnknownPaneFunctionError(name, bank.details, null, bank.message);
-  const near = nearFunctionCodes(registry, name);
+  // A word that asks for a function's data (IVOL for HIVG and OVDV) names them as a slip from a code names it.
+  const suggested = suggestedFunctionCodes(registry, name);
+  const near = [...suggested, ...nearFunctionCodes(registry, name).filter(({ code }) => !suggested.some((entry) => entry.code === code))];
   // A catalog that cannot be read still leaves the pointer to it.
   const closest = (await suggestPaneFunctions(registry, context, name).catch(logFailure("cli.pane-functions-resolver", "Find pane function suggestions failed", [])))
     .filter((entry) => !near.some(({ code }) => code === entry.token));
   const tokenWidth = Math.max(0, ...closest.map((entry) => entry.token.length));
   const word = /^[\w.:-]+$/.test(name) ? name : JSON.stringify(name);
   const argument = arg.trim() ? ` ${/^[\w.:,=%+@/$^-]+$/.test(arg.trim()) ? arg.trim() : JSON.stringify(arg.trim())}` : "";
+  // One code is run on the argument; the functions a word asks for are each.
+  const runs = suggested.length > 0 ? suggested : near.length === 1 ? near : [];
   return new UnknownPaneFunctionError(name, [
-    ...near.length === 1 ? [`Run: gloomberb ${command} ${near[0]!.code}${argument}`] : [],
+    // A function a word asks for, typed with no argument, shows the one it takes (`<ticker>`).
+    ...runs.map(({ code }, index) => [index === 0 ? "Run:" : "    ", "gloomberb", command, code,
+      argument.trim() || (suggested.length > 0 ? findFunctionCode(registry, code)?.argument : "")].filter(Boolean).join(" ")),
     ...closest.length > 0
       ? ["Closest matches:", ...closest.map((entry) => `  ${entry.token.padEnd(tokenWidth)}  ${entry.label}`), `Search the catalog: gloomberb catalog ${word}`]
       : near.length > 0 ? [] : [`No function code is close to ${word}. List every function: gloomberb catalog`],
@@ -317,7 +332,7 @@ export async function resolvePaneFunction(
     options: normalizedOptions,
     ...(tableSection !== undefined ? { tableSection } : {}),
   };
-  resolved.instance = await buildPaneInstance(resolved, context, args.arg);
+  resolved.instance = await buildPaneInstance(resolved, context, args.arg, resolutionSettings.command ?? "fn");
   return resolved;
 }