gloomberb 0.18.2 → 0.18.4

package/src/cli/name-entries.ts

@@ -3,32 +3,81 @@ import type { DataProvider } from "../types/data-provider";
 import { findListingOfCompanyName, isCompanyNameInput, readTerminalCodeArg } from "../tickers/company-name-listing";
 import { isNotATickerMessage } from "./not-a-ticker";
 import { splitSymbolWords } from "./symbol-args";
-import { isProviderBusy } from "../sources/provider-errors";
+import { isNumberCell } from "./symbol-cells";
+import { isProviderBusy, type ProviderBusyError } from "../sources/provider-errors";
+import { unknownBloombergMarket } from "../tickers/terminal-codes";
 
 /**
- * The entries of a list (`splitSymbolArgs`) as the symbols a command
- * resolves. An entry with a space in it is a company's name when search finds
- * the company (`Whirlpool Corporation`), and stays whole for its listing to
- * say what it was read as; otherwise it is its words, each a symbol, as a
- * pasted line always was (`brk.b bf-b`). Only those entries cost a search.
- * One search was too busy to look up also stays whole, so its lookup says so
- * instead of resolving its words as symbols of other companies.
+ * The entries of a list (`splitSymbolArgs`, or a file's lines) as the symbols
+ * a command resolves. An entry with a space in it is a company's name when
+ * search finds the company (`Whirlpool Corporation`, `philip morris intl`),
+ * and stays whole for its listing to say what it was read as. One search
+ * finds no company for is its words, each a symbol, when each is written as
+ * a symbol or has a quote (`AAPL MSFT`, `brk.b bf-b`, `aapl msft` on a
+ * pasted line), and otherwise stays whole, a name nothing lists: its words
+ * are not taken for other companies' symbols (INTL, a fund, from a misspelt
+ * `phillip morris intl`). Only those entries cost a search. One search was
+ * too busy to look up is its words only when each has a quote (`GME AMC`),
+ * as `readPhraseArgument` reads a quoted line, and otherwise stays whole, so
+ * its lookup says so instead of resolving its words as symbols of other
+ * companies.
  */
 export async function readNameEntries(
   entries: readonly string[],
-  dataProvider: Pick<DataProvider, "search">,
+  dataProvider: Pick<DataProvider, "search"> & Partial<Pick<DataProvider, "getQuotesBatch" | "getQuote">>,
 ): Promise<string[]> {
-  const read = await Promise.all(entries.map(async (entry) => (
-    // A terminal's code for a listing ("JPM US Equity") is one entry, like a company's name.
-    await readTerminalCodeArg(dataProvider, entry) || (isCompanyNameInput(entry) && await findListingOfCompanyName(dataProvider, entry).catch(busyAsFound))
-      ? [entry] : splitSymbolWords([entry])
-  )));
+  const read = await Promise.all(entries.map(async (entry) => {
+    // A terminal's code for a listing ("JPM US Equity", "VOD LN") is one entry, like a company's name, and so is a
+    // line written as one whose market code is unknown ("AAPL GP"): its lookup refuses it, never AAPL and GP.
+    if (unknownBloombergMarket(entry) || await readTerminalCodeArg(dataProvider, entry)) return [entry];
+    if (!isCompanyNameInput(entry)) return splitSymbolWords([entry]);
+    const named = await findListingOfCompanyName(dataProvider, entry).catch(busyAsAnswer);
+    const busy = isProviderBusy(named);
+    if (named && !busy) return [entry];
+    const words = splitSymbolWords([entry]);
+    return await wordsAreSymbols(words, dataProvider, { quoteEvery: busy }) ? words : [entry];
+  }));
   return read.flat();
 }
 
-/** `findListingOfCompanyName`'s busy answer as a name to keep whole, any other failure as it is. */
-function busyAsFound(error: unknown): true {
-  if (isProviderBusy(error)) return true;
+/** A word typed as a ticker is: in capitals (AAPL, 7203.T), with a venue or class mark (brk.b, bf-b, SAN:EPA), or after a $. */
+function writtenAsSymbol(word: string): boolean {
+  return /^\$|[:.\-/=^]/.test(word) || /\d/.test(word) || (/\p{Lu}/u.test(word) && !/\p{Ll}/u.test(word));
+}
+
+/**
+ * Whether the words of an entry search found no company for are symbols:
+ * each written as one (2222, BRK.B) or else with a quote, the others asked in
+ * one batch (`2222 amd pltr`). With `quoteEvery`, for an entry search was too
+ * busy to look up, each but a listing (SAN:EPA) needs a quote, as words in
+ * capitals can be a name too (BANK OF AMERICA). A batch that fails says
+ * nothing, and the entry stays a name.
+ */
+async function wordsAreSymbols(
+  words: readonly string[],
+  dataProvider: Partial<Pick<DataProvider, "getQuotesBatch" | "getQuote">>,
+  { quoteEvery = false }: { quoteEvery?: boolean } = {},
+): Promise<boolean> {
+  const symbols = words.filter((word) => quoteEvery ? !word.includes(":") : !writtenAsSymbol(word)).map((word) => word.replace(/^\$/, "").toUpperCase());
+  if (symbols.length === 0) return true;
+  if (dataProvider.getQuotesBatch) {
+    const results = await dataProvider.getQuotesBatch(symbols.map((symbol) => ({ symbol, exchange: "" })))
+      .catch(logFailure("cli.name-entries", "Read quotes for a pasted line failed", []));
+    return results.length === symbols.length && results.every(({ quote }) => !!quote);
+  }
+  // A source without batches is asked a quote at a time: the few words not written as symbols.
+  const { getQuote } = dataProvider;
+  if (!getQuote) return false;
+  const quoted = await Promise.all(symbols.map((symbol) => getQuote(symbol, "").then(
+    (quote) => !!quote,
+    logFailure("cli.name-entries", "Read a quote for a pasted line failed", false),
+  )));
+  return quoted.every(Boolean);
+}
+
+/** `findListingOfCompanyName`'s busy answer, returned for the words to be read without it; any other failure as it is. */
+function busyAsAnswer(error: unknown): ProviderBusyError {
+  if (isProviderBusy(error)) return error;
   throw error;
 }
 
@@ -44,7 +93,8 @@ export type PhraseReading =
  * word is one the source says is not a ticker (`"AAPL MSFT"`), else a phrase
  * (`"10 year yield"`), which is never split into symbols such as YEAR and
  * YIELD. The words are asked in one batch beside the name search, not a
- * request each; a word written as a listing (`SAN:EPA`) is taken as one.
+ * request each; a word written as a listing (`SAN:EPA`) is taken as one, and
+ * a number (`10.5`, `5.25%`) is never asked: it makes the line a phrase.
  * When search is too busy to say whether it names a company, a line whose
  * every word has a quote is still symbols; anything else throws
  * `ProviderBusyError`, as its words may be other companies' symbols.
@@ -53,9 +103,10 @@ export async function readPhraseArgument(
   phrase: string,
   dataProvider: Pick<DataProvider, "search" | "getQuotesBatch">,
 ): Promise<PhraseReading> {
-  if (await readTerminalCodeArg(dataProvider, phrase)) return { kind: "symbols", symbols: [phrase] };
+  if (unknownBloombergMarket(phrase) || await readTerminalCodeArg(dataProvider, phrase)) return { kind: "symbols", symbols: [phrase] };
   const words = splitSymbolWords([phrase]);
-  const asked = words.filter((word) => !word.includes(":")).map((word) => word.replace(/^\$/, "").toUpperCase());
+  const numbered = words.some(isNumberCell);
+  const asked = words.filter((word) => !word.includes(":") && !isNumberCell(word)).map((word) => word.replace(/^\$/, "").toUpperCase());
   const [named, results] = await Promise.all([
     findListingOfCompanyName(dataProvider, phrase).catch((error: unknown) => {
       if (isProviderBusy(error)) return error;
@@ -66,11 +117,11 @@ export async function readPhraseArgument(
       : [],
   ]);
   if (isProviderBusy(named)) {
-    if (results.length === asked.length && results.every(({ quote }) => !!quote)) return { kind: "symbols", symbols: words };
+    if (!numbered && results.length === asked.length && results.every(({ quote }) => !!quote)) return { kind: "symbols", symbols: words };
     throw named;
   }
   if (named) return { kind: "name", name: phrase };
   // A word the source could not answer for (an outage) is given the benefit of the doubt, as the line was before.
-  const notTicker = results.some(({ quote, error }) => !quote && isNotATickerMessage(error instanceof Error ? error.message : String(error ?? "")));
+  const notTicker = numbered || results.some(({ quote, error }) => !quote && isNotATickerMessage(error instanceof Error ? error.message : String(error ?? "")));
   return notTicker ? { kind: "phrase", phrase } : { kind: "symbols", symbols: words };
 }

package/src/cli/native-smoke.ts

@@ -7,6 +7,8 @@ export async function smokeOpenTuiNative(): Promise<void> {
 }
 
 export async function smokeOpenTuiRuntime(): Promise<void> {
+  const { loadRenderLib } = await import("../renderers/opentui/render-lib");
+  await loadRenderLib();
   await import("../renderers/opentui/start");
   const { assertRendersLeaveNoTimingEntries } = await import("../renderers/opentui/render-timing-smoke");
   await assertRendersLeaveNoTimingEntries();

package/src/cli/not-a-ticker.ts

@@ -5,7 +5,7 @@ import { treasuryYieldHint, treasuryYieldTenor } from "./treasury-yields";
 
 // "Not a ticker: APPLE." as the router words it; the symbol ends at the sentence's own period.
 // One that already names what to try (a search, a FRED series, a yield, the pair search offered) is left alone.
-const NOT_A_TICKER_SENTENCE = /Not a ticker: ((?:(?!\.\s)[^\n`\x1b])+?)\.(?=\s|\x1b|$)(?! Try `gloomberb (?:search|fred|quote) | Did you mean )/g;
+const NOT_A_TICKER_SENTENCE = /Not a ticker: ((?:(?!\.\s)[^\n`\x1b])+?)\.(?=\s|\x1b|$)(?! Try `gloom (?:search|fred|quote) | Did you mean )/g;
 
 /**
  * The symbol as the user typed it on the command line (`Apple`), not as the router saw it (`APPLE`).
@@ -25,13 +25,13 @@ function typedSymbol(symbol: string, args: readonly string[]): string {
   return symbol;
 }
 
-/** "Try `gloomberb search Apple`." naming what the user typed; a venue (`Apple:NYSE`) is not part of a search. */
+/** "Try `gloom search Apple`." naming what the user typed; a venue (`Apple:NYSE`) is not part of a search. */
 function searchHint(typed: string): string {
   const query = typed.split(":")[0]!.trim() || typed;
-  return `Try \`gloomberb search ${/\s/.test(query) ? JSON.stringify(query) : query}\`.`;
+  return `Try \`gloom search ${/\s/.test(query) ? JSON.stringify(query) : query}\`.`;
 }
 
-/** Whether an id is a FRED series the catalog charts (DFEDTARU), which `gloomberb fred` prints. */
+/** Whether an id is a FRED series the catalog charts (DFEDTARU), which `gloom fred` prints. */
 export type FredSeriesCheck = (seriesId: string) => boolean;
 
 /**
@@ -40,20 +40,30 @@ export type FredSeriesCheck = (seriesId: string) => boolean;
  * series id (DFEDTARU) is no ticker search finds, so its hint is the `fred` command instead, a
  * coin on the crypto board typed bare (USDT, TETHER) names its one symbol, USDT-USD, once
  * `primeBoardCoins` has read the board, and a Treasury yield typed as a ticker (US10Y) names the
- * commands that have it.
+ * commands that have it. A one-word company name a line says was read as a listing ("Read
+ * "APPLE" as AAPL:NASDAQ") is put back in the user's spelling too.
  */
 export function withSearchHints(text: string, args: readonly string[], isFredSeries: FredSeriesCheck = () => false): string {
-  return text.includes("Not a ticker: ")
-    ? text.replace(NOT_A_TICKER_SENTENCE, (sentence, symbol: string) => {
+  const named = withTypedNames(text, args);
+  return named.includes("Not a ticker: ")
+    ? named.replace(NOT_A_TICKER_SENTENCE, (sentence, symbol: string) => {
       const typed = typedSymbol(symbol, args);
       const id = typed.toUpperCase();
-      if (/^[A-Z0-9]+$/.test(id) && isFredSeries(id)) return `${sentence} Try \`gloomberb fred ${id}\`.`;
+      if (/^[A-Z0-9]+$/.test(id) && isFredSeries(id)) return `${sentence} Try \`gloom fred ${id}\`.`;
       const coin = boardCoinFor(id);
       if (coin) return `${sentence} Did you mean ${coin.symbol}${coin.name && coin.name.toUpperCase() !== coin.symbol ? ` (${coin.name})` : ""}?`;
       const tenor = treasuryYieldTenor(typed);
       return `${sentence} ${tenor ? treasuryYieldHint(tenor) : searchHint(typed)}`;
     })
-    : text;
+    : named;
+}
+
+// "Read "APPLE" as AAPL:NASDAQ (Apple Inc.)." as a list reads a one-word name, upper-cased like a symbol.
+const READ_AS_NAME = /Read "([^"\n]+)" as /g;
+
+/** A company's name the line says was read as a listing, in the user's own spelling from `args` (`Apple`). */
+function withTypedNames(text: string, args: readonly string[]): string {
+  return text.includes("Read \"") ? text.replace(READ_AS_NAME, (_line, name: string) => `Read "${typedSymbol(name, args)}" as `) : text;
 }
 
 /**

package/src/cli/opentui-libc.ts

@@ -0,0 +1,5 @@
+import { detectLinuxLibc, selectOpenTuiLibc } from "../utils/linux-libc";
+
+// Imported before anything else by every entry: @opentui/core picks its
+// native library the moment it loads.
+selectOpenTuiLibc(process.env, detectLinuxLibc());

package/src/cli/options.ts

@@ -4,6 +4,13 @@ export interface CliGlobalOptions {
   format: CliOutputFormat;
   quiet: boolean;
   color: boolean | null;
+  /**
+   * `--plain`: tables without rules, arrows in words, every column kept with
+   * "—" for an empty cell (`setCliPlainOverride`); `--no-plain` turns it
+   * off. Null leaves it to the environment: on with NO_COLOR set to a value,
+   * or when stdout is not a terminal (`plainByDefault`).
+   */
+  plain: boolean | null;
   limit?: number;
   /** `--tail <n>`: the newest n rows of a dated series, in their printed order. Never set with `limit`. */
   tail?: number;
@@ -31,6 +38,7 @@ export const DEFAULT_CLI_OPTIONS: CliGlobalOptions = {
   format: "text",
   quiet: false,
   color: null,
+  plain: null,
   refresh: false,
   dryRun: false,
   yes: false,
@@ -110,6 +118,10 @@ export function parseCliGlobalArgs(rawArgs: string[]): ParsedCliArgs {
       options.color = true;
       continue;
     }
+    if (arg === "--plain" || arg === "--no-plain") {
+      options.plain = arg === "--plain";
+      continue;
+    }
     if (arg === "--refresh") {
       options.refresh = true;
       continue;

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

@@ -18,6 +18,8 @@ export interface PaneFunctionCapability {
   botSafe: boolean;
   tickerCardinality: PaneFunctionTickerCardinality;
   aliases: string[];
+  /** Words that are no code but ask for this function's data: `fn` and `catalog` answer them with it. */
+  suggestFor?: string[];
   intents: string[];
   outputKind: string;
   reportReadiness: PaneFunctionReadiness;
@@ -25,6 +27,8 @@ export interface PaneFunctionCapability {
   dataRequirements: string[];
   limitations: string[];
   options: PaneFunctionOptionDef[];
+  /** A rendered view that refuses any option it does not declare (PaneDef.reportOptionsOnly), as a headless report does. */
+  strictOptions?: boolean;
 }
 
 const NON_DATA_PANE_IDS = new Set([
@@ -66,6 +70,7 @@ function fallbackCapability(
       ? RENDERED_VIEW_LIMITATION
       : "This pane is an interactive surface and does not expose a data report."],
     options: [...(pane.reportOptions ?? [])],
+    ...pane.reportOptionsOnly ? { strictOptions: true } : {},
   };
 }
 
@@ -77,6 +82,14 @@ function optionToken(value: string): string {
   return value.trim().toLowerCase().replace(/[\s_.-]+/g, "");
 }
 
+/**
+ * An option as an error names it, the way it is typed on the command line:
+ * `--as-of` for the `asOf` the parser reads `--as-of` (or `--asOf`) into.
+ */
+export function optionFlag(key: string): string {
+  return `--${key.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase()}`;
+}
+
 // Choices longer than this move from the flag into its description, where they can wrap.
 export const MAX_INLINE_CHOICES = 24;
 
@@ -88,7 +101,7 @@ export function optionChoices(option: PaneFunctionOptionDef): string[] {
 export function optionFlags(option: PaneFunctionOptionDef): string {
   const choices = optionChoices(option).join("|");
   const value = choices && choices.length <= MAX_INLINE_CHOICES ? choices : option.values?.length ? "value" : option.placeholder ?? option.type;
-  return `--${option.key} <${value}>`;
+  return `${optionFlag(option.key)} <${value}>`;
 }
 
 /** The option values a typed word is, by value or alias: `gas` is JODI's `--commodity gas`. */
@@ -97,18 +110,29 @@ function optionValueOf(options: readonly PaneFunctionOptionDef[], typed: string)
   for (const option of options) {
     const value = option.values?.find((candidate) => optionToken(candidate.value) === token
       || candidate.aliases?.some((alias) => optionToken(alias) === token));
-    if (value) return `--${option.key} ${value.value}`;
+    if (value) return `${optionFlag(option.key)} ${value.value}`;
   }
   return null;
 }
 
+/** Options that name an underlying listing, which a ticker typed after the function is meant for. */
+const LISTING_OPTION_KEYS = new Set(["symbol", "ticker", "underlying"]);
+
+/** `--symbol NEM` for a word that reads as a ticker (NEM, BHP:ASX, 7203.T), when the function takes one as an option. */
+function listingOptionOf(options: readonly PaneFunctionOptionDef[], typed: string): string | null {
+  const word = typed.trim();
+  if (!/^[A-Za-z0-9^][A-Za-z0-9.:=^&-]{0,23}$/.test(word) || !/[A-Za-z]/.test(word)) return null;
+  const option = options.find(({ key, type }) => type === "string" && LISTING_OPTION_KEYS.has(optionToken(key)));
+  return option ? `${optionFlag(option.key)} ${word}` : null;
+}
+
 /** An option in use, as typed after the function: its own example, else a choice that is not the default. */
 function optionExample(option: PaneFunctionOptionDef): string {
   if (option.example) return option.example;
-  if (option.type === "boolean") return `--${option.key}`;
+  if (option.type === "boolean") return optionFlag(option.key);
   const choice = option.values?.find(({ value }) => value !== option.defaultValue);
-  if (choice) return `--${option.key} ${choice.value}`;
-  return `--${option.key} <${option.placeholder ?? option.type}>`;
+  if (choice) return `${optionFlag(option.key)} ${choice.value}`;
+  return `${optionFlag(option.key)} <${option.placeholder ?? option.type}>`;
 }
 
 /** Options a no-argument error lists before it points at the catalog for the rest. */
@@ -117,7 +141,8 @@ const LISTED_OPTIONS = 6;
 /**
  * What a function that takes no argument answers one with: its options and a
  * command to run. A word that is one of an option's values runs as that option
- * (`fn JODI gas` is `fn JODI --commodity gas`); anything else gets an option's example.
+ * (`fn JODI gas` is `fn JODI --commodity gas`), and a ticker runs as the option that takes one
+ * (`fn OVME NEM` is `fn OVME --symbol NEM`); anything else gets an option's example.
  */
 export function noArgumentMessage(
   options: readonly PaneFunctionOptionDef[],
@@ -126,11 +151,11 @@ export function noArgumentMessage(
   command: "fn" | "shot" = "fn",
 ): string {
   const head = `${code} does not accept an argument.`;
-  if (options.length === 0) return `${head} Run: gloomberb ${command} ${code}`;
-  const asOption = optionValueOf(options, typed);
+  if (options.length === 0) return `${head} Run: gloom ${command} ${code}`;
+  const asOption = optionValueOf(options, typed) ?? listingOptionOf(options, typed);
   const listed = options.slice(0, LISTED_OPTIONS).map(optionFlags).join(", ");
-  const more = options.length > LISTED_OPTIONS ? ` and ${options.length - LISTED_OPTIONS} more (gloomberb catalog ${code})` : "";
-  const run = asOption ? `Run: gloomberb ${command} ${code} ${asOption}` : `Example: gloomberb ${command} ${code} ${optionExample(options[0]!)}`;
+  const more = options.length > LISTED_OPTIONS ? ` and ${options.length - LISTED_OPTIONS} more (gloom catalog ${code})` : "";
+  const run = asOption ? `Run: gloom ${command} ${code} ${asOption}` : `Example: gloom ${command} ${code} ${optionExample(options[0]!)}`;
   return `${head} Options: ${listed}${more}. ${run}`;
 }
 
@@ -160,6 +185,30 @@ export function getHeadlessPaneDefinition(
   return template?.headless ?? pane.headless;
 }
 
+/** What a function takes after its code: its kind and the name the catalog gives it. */
+export interface PaneFunctionArgument {
+  kind?: string;
+  placeholder?: string;
+}
+
+/**
+ * The argument a function takes, as the catalog writes it and `fn` checks it:
+ * the `headless` model's, else the template shortcut's, else the one a
+ * rendered view declares (`reportArgument`).
+ */
+export function paneFunctionArgument(template: PaneTemplateDef | undefined, pane: PaneDef): PaneFunctionArgument {
+  const headless = getHeadlessPaneDefinition(template, pane);
+  return {
+    kind: headless?.argument.kind ?? template?.shortcut?.argKind ?? pane.reportArgument?.kind,
+    placeholder: headless?.argument.placeholder ?? template?.shortcut?.argPlaceholder ?? pane.reportArgument?.placeholder,
+  };
+}
+
+/** A function the catalog lists with no argument, which refuses one as CBR does. */
+export function takesNoArgument({ kind, placeholder }: PaneFunctionArgument): boolean {
+  return !placeholder && (!kind || kind === "none");
+}
+
 export function getPaneFunctionCapability(
   template: PaneTemplateDef | undefined,
   pane: PaneDef,
@@ -207,7 +256,7 @@ function normalizeEnumValue(option: PaneFunctionOptionDef, rawValue: string, arg
   if (match) return match.value;
   const hint = option.invalidValueHint?.(rawValue, argument);
   throw new Error(
-    `Invalid --${option.key} value "${rawValue}".${hint ? ` ${hint}` : ""} Use one of: ${option.values?.map(({ value }) => value).join(", ") ?? ""}.`,
+    `Invalid ${optionFlag(option.key)} value "${rawValue}".${hint ? ` ${hint}` : ""} Use one of: ${option.values?.map(({ value }) => value).join(", ") ?? ""}.`,
   );
 }
 
@@ -220,19 +269,19 @@ function normalizeOptionValue(
     if (rawValue === true) return true;
     if (/^true$/i.test(rawValue)) return true;
     if (/^false$/i.test(rawValue)) return false;
-    throw new Error(`Invalid --${option.key} value "${rawValue}". Use true or false.`);
+    throw new Error(`Invalid ${optionFlag(option.key)} value "${rawValue}". Use true or false.`);
   }
-  if (rawValue === true) throw new Error(`--${option.key} requires a value.`);
+  if (rawValue === true) throw new Error(`${optionFlag(option.key)} requires a value.`);
   if (option.normalize) return option.normalize(rawValue);
   if (option.type === "enum") return normalizeEnumValue(option, rawValue, argument);
   if (option.type === "integer") {
     const value = Number(rawValue);
-    if (!Number.isInteger(value)) throw new Error(`--${option.key} must be an integer.`);
+    if (!Number.isInteger(value)) throw new Error(`${optionFlag(option.key)} must be an integer.`);
     if (option.minimum != null && value < option.minimum) {
-      throw new Error(`--${option.key} must be at least ${option.minimum}.`);
+      throw new Error(`${optionFlag(option.key)} must be at least ${option.minimum}.`);
     }
     if (option.maximum != null && value > option.maximum) {
-      throw new Error(`--${option.key} must be at most ${option.maximum}.`);
+      throw new Error(`${optionFlag(option.key)} must be at most ${option.maximum}.`);
     }
     return value;
   }
@@ -248,7 +297,7 @@ export function normalizeCapabilityOptions(
    */
   settings: { strict?: boolean; code?: string; argument?: string | null } = {},
 ): NormalizedPaneFunctionOptions {
-  if (!capability.botSafe) {
+  if (!capability.botSafe && !capability.strictOptions) {
     // A rendered view takes any pane setting; the options it declares are checked.
     return Object.fromEntries(Object.entries(options).map(([key, value]) => {
       const option = findCapabilityOption(capability, key);
@@ -260,20 +309,27 @@ export function normalizeCapabilityOptions(
   for (const option of capability.options) {
     if (option.defaultValue !== undefined) normalized[option.key] = option.defaultValue;
   }
+  // Each option typed, by its key, as the user wrote it (`--window` for RETURN's --range).
+  const typed = new Map<string, string>();
   for (const [rawKey, rawValue] of Object.entries(options)) {
     const option = findCapabilityOption(capability, rawKey);
+    if (option) typed.set(option.key, rawKey);
     if (!option) {
       if (settings.strict === false) {
         normalized[rawKey] = rawValue;
         continue;
       }
-      const supported = capability.options.map(({ key }) => `--${key}`).join(", ");
+      const supported = capability.options.map(({ key }) => optionFlag(key)).join(", ");
       throw new Error(
-        `${settings.code ?? capability.id} does not support --${rawKey}.${supported ? ` Supported options: ${supported}.` : " It has no options."}`,
+        `${settings.code ?? capability.id} does not support ${optionFlag(rawKey)}.${supported ? ` Supported options: ${supported}.` : " It has no options."}`,
       );
     }
     normalized[option.key] = normalizeOptionValue(option, rawValue, settings.argument);
   }
+  for (const [key, rawKey] of typed) {
+    const replaced = findCapabilityOption(capability, key)?.replaces?.find((other) => typed.has(other));
+    if (replaced) throw new Error(`${optionFlag(rawKey)} replaces ${optionFlag(typed.get(replaced)!)}; give one of them.`);
+  }
   return normalized;
 }
 
@@ -283,7 +339,8 @@ export function capabilityPaneSettings(
 ): Record<string, unknown> {
   const settings: Record<string, unknown> = {};
   for (const option of capability.options) {
-    if (option.pluginState) continue;
+    // An option read from pane state sets no setting, unless it also names one.
+    if (option.pluginState && !option.settingKey) continue;
     const value = options[option.key];
     if (value !== undefined) settings[option.settingKey ?? option.key] = value;
   }

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

@@ -13,6 +13,7 @@ import {
   MAX_INLINE_CHOICES,
   optionChoices,
   optionFlags,
+  paneFunctionArgument,
   type PaneFunctionCapability,
   type PaneFunctionOptionDef,
   type PaneFunctionReadiness,
@@ -153,12 +154,8 @@ export function findFunctionCode(registry: PaneFunctionCatalog, token: string):
     ...(headless?.discovery?.aliases ?? []),
   ];
   if (!codes.some((code) => code && normalizeLookupToken(code) === wanted)) return null;
-  return {
-    argument: argumentHint({
-      argKind: headless?.argument.kind ?? found.shortcut?.argKind,
-      argPlaceholder: headless?.argument.placeholder ?? found.shortcut?.argPlaceholder,
-    }),
-  };
+  const argument = pane ? paneFunctionArgument(found, pane) : { kind: found.shortcut?.argKind, placeholder: found.shortcut?.argPlaceholder };
+  return { argument: argumentHint({ argKind: argument.kind, argPlaceholder: argument.placeholder }) };
 }
 
 /** A function code a typed one is a slip away from: what to type, and the function's name. */
@@ -184,7 +181,7 @@ const NEAR_CODE_LIMIT = 3;
  * among the mnemonics the command bar takes, each named by the code it is
  * near (`DES` for Ticker Research, whose code is T). Empty when none is that
  * close, the name is too short to tell, or so many are that none stands out.
- * A word typed as a command (`commandWord`, `gloomberb RCDF PLTR`) is held to
+ * A word typed as a command (`commandWord`, `gloom RCDF PLTR`) is held to
  * MIN_COMMAND_WORD_TYPO_LENGTH and the code's first letter, so a ticker typed
  * there is not taken for a code.
  */
@@ -210,6 +207,21 @@ export function nearFunctionCodes(
     .sort((left, right) => left.code.localeCompare(right.code));
 }
 
+/**
+ * The functions a word that is no code asks for (`IVOL`, `IV`: HIVG and
+ * OVDV), as their `discovery.suggestFor` lists it, each by its code.
+ */
+export function suggestedFunctionCodes(registry: PaneFunctionCatalog, name: string): NearFunctionCode[] {
+  const wanted = normalizeLookupToken(name);
+  if (!wanted) return [];
+  return [...registry.paneTemplates.values()].flatMap((template) => {
+    const pane = registry.panes.get(template.paneId);
+    const words = pane ? getHeadlessPaneDefinition(template, pane)?.discovery?.suggestFor ?? [] : [];
+    const code = template.shortcut?.prefix;
+    return code && words.some((word) => normalizeLookupToken(word) === wanted) ? [{ code: code.toUpperCase(), label: template.label }] : [];
+  }).sort((left, right) => left.code.localeCompare(right.code));
+}
+
 function sampleArgForTemplate(template: PaneTemplateDef): string {
   switch (template.shortcut?.argKind) {
     case "ticker":
@@ -244,6 +256,7 @@ async function buildTemplateCatalogEntry(
   }
 
   const headless = getHeadlessPaneDefinition(template, pane);
+  const argument = paneFunctionArgument(template, pane);
   return {
     token: template.shortcut?.prefix ?? template.id,
     label: template.label,
@@ -253,8 +266,8 @@ async function buildTemplateCatalogEntry(
     templateId: template.id,
     shortcut: template.shortcut?.prefix,
     aliases: [...(template.shortcut?.aliases ?? [])],
-    argKind: headless?.argument.kind ?? template.shortcut?.argKind,
-    argPlaceholder: headless?.argument.placeholder ?? template.shortcut?.argPlaceholder,
+    argKind: argument.kind,
+    argPlaceholder: argument.placeholder,
     ...(headless?.argument.examples?.length ? { argExamples: headless.argument.examples } : {}),
     ...(headless?.argument.kind === "tickers" && template.shortcut?.argKind === "ticker"
       ? { shotArgument: argumentHint({ argKind: "ticker", argPlaceholder: template.shortcut.argPlaceholder }) } : {}),
@@ -281,6 +294,7 @@ export async function buildPaneCatalogEntries(
   for (const pane of registry.panes.values()) {
     if (templatedPaneIds.has(pane.id)) continue;
     const [shortcut, ...aliases] = builtInPanePrefixes(pane.id);
+    const argument = paneFunctionArgument(undefined, pane);
     entries.push({
       token: shortcut ?? pane.id,
       label: pane.name,
@@ -289,8 +303,8 @@ export async function buildPaneCatalogEntries(
       paneName: pane.name,
       shortcut,
       aliases,
-      argKind: pane.headless?.argument.kind,
-      argPlaceholder: pane.headless?.argument.placeholder,
+      argKind: argument.kind,
+      argPlaceholder: argument.placeholder,
       ...(pane.headless?.argument.examples?.length ? { argExamples: pane.headless.argument.examples } : {}),
       keywords: [],
       defaultSettings: {},
@@ -391,6 +405,7 @@ function scorePaneCatalogEntry(entry: PaneCatalogEntry, query: string): CatalogM
     entry.token,
     entry.shortcut,
     ...entry.aliases,
+    ...entry.capability.suggestFor ?? [],
     entry.templateId,
     entry.paneId,
   ].filter((value): value is string => !!value).map((value) => normalizeLookupToken(value));
@@ -560,7 +575,8 @@ function readinessCell(readiness: PaneFunctionReadiness): string {
 function optionDescription(option: PaneFunctionOptionDef): string {
   const choices = optionChoices(option);
   const parts = [option.description.replace(/\.$/, "")];
-  if (choices.join("|").length > MAX_INLINE_CHOICES) parts.push(`One of ${choices.join(", ")}`);
+  // 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 (option.defaultValue !== undefined && option.defaultValue !== "") parts.push(`Default ${String(option.defaultValue)}`);
   return `${parts.join(". ")}.`;
 }
@@ -606,14 +622,14 @@ function renderCatalogEntry(entry: PaneCatalogEntry): string {
 
   lines.push("", renderSection("Examples"));
   if (capability.reportReadiness !== "unsupported") {
-    lines.push(...wrapCommandLine(`gloomberb fn ${invocation}`, width));
-    for (const example of entry.argExamples ?? []) lines.push(...wrapCommandLine(`gloomberb fn ${entry.token} ${example}`, width));
+    lines.push(...wrapCommandLine(`gloom fn ${invocation}`, width));
+    for (const example of entry.argExamples ?? []) lines.push(...wrapCommandLine(`gloom fn ${entry.token} ${example}`, width));
     for (const option of capability.options) {
-      if (option.example) lines.push(...wrapCommandLine(`gloomberb fn ${option.exampleWithoutArgument ? entry.token : invocation} ${option.example}`, width));
+      if (option.example) lines.push(...wrapCommandLine(`gloom fn ${option.exampleWithoutArgument ? entry.token : invocation} ${option.example}`, width));
     }
   }
   const shotInvocation = entry.shotArgument ? `${entry.token} ${entry.shotArgument}` : invocation;
-  lines.push(...wrapCommandLine(`gloomberb shot ${shotInvocation} --output ${entry.token.toLowerCase()}.png`, width));
+  lines.push(...wrapCommandLine(`gloom shot ${shotInvocation} --output ${entry.token.toLowerCase()}.png`, width));
   return lines.join("\n");
 }
 
@@ -622,10 +638,11 @@ function renderMatchesTable(shown: readonly PaneCatalogEntry[]): string {
   return renderTable(
     [
       { header: "Function", shrink: false },
-      { header: "Name", maxWidth: 20 },
-      { header: "Argument", maxWidth: 14 },
+      { header: "Name" },
+      { header: "Argument" },
       { header: "Report" },
-      { header: "Description" },
+      // A scan list: the description is cut where it does not fit, and `catalog <function>` prints it whole.
+      { header: "Description", shrink: true, minWidth: 20 },
     ],
     shown.map((entry) => [
       cliStyles.command(entry.token),
@@ -659,7 +676,7 @@ function renderAlsoMatches(exact: PaneCatalogEntry, entries: readonly PaneCatalo
  */
 export function renderFunctionHelp(entry: PaneCatalogEntry, command: string): string {
   const width = Math.min(cliTerminalWidth() ?? CATALOG_TEXT_WIDTH, CATALOG_TEXT_WIDTH);
-  const note = `The options every function takes, and the output formats, are in gloomberb help ${command}.`;
+  const note = `The options every function takes, and the output formats, are in gloom help ${command}.`;
   return [renderCatalogEntry(entry), "", ...wrapText(note, width).map((line) => cliStyles.muted(line))].join("\n");
 }
 
@@ -671,7 +688,7 @@ function renderCatalogGlossary(glossary: GlossaryLookup, width: number): string
   const defined = glossary.exact.length > 0 ? [renderSection("Glossary"), ...renderGlossaryEntries(glossary.exact)] : [];
   const others = glossary.partial.map((entry) => entry.term).join(", ");
   const related = others
-    ? wrapText(`${defined.length > 0 ? "Related" : "Glossary"}: ${others}. gloomberb catalog glossary <term> explains one.`, width)
+    ? wrapText(`${defined.length > 0 ? "Related" : "Glossary"}: ${others}. gloom catalog glossary <term> explains one.`, width)
       .map((line) => cliStyles.muted(line))
     : [];
   return [...defined, ...related].join("\n");
@@ -720,7 +737,7 @@ export function renderPaneCatalogReport(
     if (charted) return withGap([charted, terms].filter(Boolean).join("\n\n"));
     if (glossary.exact.length > 0 || gap || setting) return withGap(terms);
     return withTerms(note(args.query
-      ? `No functions match "${args.query}". Run gloomberb catalog to browse them all.`
+      ? `No functions match "${args.query}". Run gloom catalog to browse them all.`
       : "No functions are available."));
   }
 
@@ -736,7 +753,7 @@ export function renderPaneCatalogReport(
     "",
     note([
       loose ? "No function carries every word of the query; these are the closest." : "",
-      "gloomberb catalog <function> shows its options and examples.",
+      "gloom catalog <function> shows its options and examples.",
       hidden > 0 ? more : "",
     ].filter(Boolean).join(" ")),
   ];