gloomberb 0.17.0 → 0.17.2

package/src/cli/commands/search.ts

@@ -23,7 +23,7 @@ import { fail } from "../errors";
 import type { MarketContext } from "../types";
 import type { CliCommandContext, GloomPlugin } from "../../types/plugin";
 import { indexRootFor, indexRootTryLine } from "../index-roots";
-import { knownGapMessage } from "../known-gaps";
+import { knownGapMessage, settingsPointer } from "../known-gaps";
 import { instrumentTypeLabel } from "../../tickers/instrument-kind";
 import { canonicalExchange, isUsListingExchange } from "../../utils/exchanges";
 import { groupByCompany } from "../../tickers/company-name";
@@ -325,9 +325,9 @@ function catalogHint(query: string): string {
 
 /**
  * The notes beside the results: the index a bare root names, data the query
- * asks for that no source carries yet, the central bank it names, and for an
- * empty search the catalog, unless a known gap, the bank or the functions
- * listed already said where to look instead.
+ * asks for that no source carries yet, the central bank it names, the setting
+ * it names ("light theme"), and for an empty search the catalog, unless one of
+ * those or the functions listed already said where to look instead.
  */
 function searchNotes(
   query: string,
@@ -337,9 +337,10 @@ function searchNotes(
 ): string[] {
   const gap = knownGapMessage(query);
   const bank = searchedCentralBank(query);
+  const setting = settingsPointer(query);
   const empty = candidates.length === 0 && !fate.stopped;
-  return [...fate.notes, indexRootNote(query, candidates), gap, bank ? centralBankLine(bank) : null,
-    empty && !gap && !bank && functions.length === 0 ? catalogHint(query) : null]
+  return [...fate.notes, indexRootNote(query, candidates), gap, bank ? centralBankLine(bank) : null, setting,
+    empty && !gap && !bank && !setting && functions.length === 0 ? catalogHint(query) : null]
     .filter((note): note is string => !!note);
 }
 
@@ -379,6 +380,8 @@ export function buildSearchReport({
   if (gap) lines.push("", gap);
   const bank = searchedCentralBank(query);
   if (bank) lines.push("", centralBankLine(bank));
+  const setting = settingsPointer(query);
+  if (setting) lines.push("", setting);
   const charted = renderSeriesMatches(query, series, SEARCH_SERIES_LIMIT, cliTerminalWidth() ?? 100, "catalog");
   // A query that names the data ("carbon", "day-ahead") lists its series first; words that happen to
   // be in a series name ("apple") list them after the tickers.
@@ -390,7 +393,7 @@ export function buildSearchReport({
   if (candidates.length === 0) {
     if (fate.stopped) return lines.join("\n");
     if (functions.length > 0) lines.push("", renderFunctionMatches(functions));
-    else if (!gap && !bank && !charted) lines.push(cliStyles.muted("No matches found."), cliStyles.muted(catalogHint(query)));
+    else if (!gap && !bank && !setting && !charted) lines.push(cliStyles.muted("No matches found."), cliStyles.muted(catalogHint(query)));
     return lines.join("\n");
   }
 

package/src/cli/commands/ticker.ts

@@ -1,6 +1,6 @@
 import { formatShortDate, parseDisplayDate } from "../../utils/datetime-format";
 import { formatReportedMoney } from "../../utils/reported-money";
-import { convertedPriceEarningsNote, epsConversionNote, fundamentalsCurrency, reportedEnterpriseValue, ttmConversionNote } from "../../utils/fundamentals";
+import { convertedPriceEarningsNote, enterpriseValueLabel, enterpriseValueReconciliationNote, epsConversionNote, fundamentalsCurrency, reportedEnterpriseValue, ttmConversionNote } from "../../utils/fundamentals";
 import { latestFinancialPeriod } from "../../utils/latest-financial-period";
 import { exportedFundamentals, formatPriceEarnings, priceEarningsOnEarnings } from "../../utils/price-earnings";
 import { describeFundamentalMarketCap, selectMarketCapitalization } from "../../utils/market-capitalization";
@@ -336,11 +336,18 @@ function reportedMoney(value: number | undefined, currency: string | undefined,
   return { text: formatReportedMoney(value, currency, perShare), value, unit: currency?.trim() || "ccy?" };
 }
 
+/** The EV line: labelled "(provider)" when it is more than 5% from market cap + debt - cash, "unavailable" when withdrawn. */
+function enterpriseValueFigure(figure: MetricFigure, fundamentals: TickerFinancials["fundamentals"]): MetricFigure {
+  const label = enterpriseValueLabel(fundamentals);
+  if (label === "unavailable") return { text: "unavailable", value: null, unit: figure.unit };
+  return label === "provider" && figure.text !== "—" ? { ...figure, text: `${figure.text} (provider)` } : figure;
+}
+
 function percentFigure(fraction: number | null | undefined, format: (value: number) => string): MetricFigure {
   return fraction != null ? { text: format(fraction), value: fraction * 100, unit: "%" } : { text: "—" };
 }
 
-/** A forward yield says what it annualizes and when, as DVD does; any other yield is the figure alone. */
+/** A forward yield says what it annualizes and when, as DVD does (a declared distribution by its ex-date); any other yield is the figure alone. */
 function forwardYieldFigure(fundamentals: TickerFinancials["fundamentals"]): MetricFigure {
   const figure = percentFigure(fundamentals?.dividendYield, formatFractionPercentCell);
   return fundamentals?.dividendYieldBasis === "forward" && fundamentals.dividendYield != null
@@ -366,7 +373,7 @@ function fundamentalsMetrics(
   const receipt = fundamentals?.sharesOutstanding != null && sharesOutstandingInReceipts(quote, fundamentals, profile?.description);
   return [
     { label: "Market Cap", ...marketCap },
-    { label: "Enterprise Value", ...enterpriseValue },
+    { label: "Enterprise Value", ...enterpriseValueFigure(enterpriseValue, fundamentals) },
     // A multiple over a loss is N/M, even beside a positive one the source served from an older period.
     { label: "P/E (TTM)", ...multipleFigure(priceEarningsOnEarnings(fundamentals?.trailingPE, fundamentals?.eps)) },
     { label: "Forward P/E", ...multipleFigure(priceEarningsOnEarnings(fundamentals?.forwardPE, fundamentals?.forwardEps)) },
@@ -404,10 +411,11 @@ function metricLines(metrics: readonly FundamentalsMetric[]): Array<[string, str
 const TRAILING_MONEY_METRICS = new Set(["EPS (TTM)", "Revenue (TTM)", "Net Income (TTM)", "Operating Cash Flow (TTM)", "Free Cash Flow (TTM)"]);
 
 /**
- * The unit notes under shown fundamentals: what a converted TTM block was converted from, an EPS in another
- * currency than the amounts beside it, and what a P/E on such an EPS divides.
+ * The notes under shown fundamentals: how a labelled or withdrawn EV compares with market cap + debt - cash, what a
+ * converted TTM block was converted from, an EPS in another currency than the amounts beside it, and what a P/E on
+ * such an EPS divides.
  */
-function trailingConversionNotes(
+function fundamentalsNotes(
   fundamentals: TickerFinancials["fundamentals"],
   metrics: readonly FundamentalsMetric[],
   quoteCurrency: string | undefined,
@@ -418,7 +426,8 @@ function trailingConversionNotes(
   const priceEarnings = metrics.some((metric) => metric.label === "P/E (TTM)" && typeof metric.value === "number")
     ? convertedPriceEarningsNote(fundamentals, quoteCurrency)
     : undefined;
-  return [conversion, eps, priceEarnings].filter((note): note is string => !!note);
+  const enterpriseValue = shown("Enterprise Value") ? enterpriseValueReconciliationNote(fundamentals) : undefined;
+  return [enterpriseValue, conversion, eps, priceEarnings].filter((note): note is string => !!note);
 }
 
 const VALUATION_METRICS = new Set(["Market Cap", "Enterprise Value", "P/E (TTM)", "Forward P/E", "PEG", "EPS (TTM)"]);
@@ -523,7 +532,7 @@ export function renderFundamentalsReport(
   const fund = fundFactsNote(symbol, financials.exchange || quote?.exchangeName, financials);
   if (lines.length === before) lines.push("", cliStyles.muted([`No ${view} reported for ${financials.symbol}.`, fund].filter(Boolean).join(" ")));
   else if (fund) lines.push(cliStyles.muted(fund));
-  for (const note of trailingConversionNotes(financials.fundamentals, metrics, quote?.currency)) lines.push(cliStyles.muted(note));
+  for (const note of fundamentalsNotes(financials.fundamentals, metrics, quote?.currency)) lines.push(cliStyles.muted(note));
   if (view === "fundamentals") appendTextSection(lines, "Description", profile?.description);
   return lines.join("\n");
 }
@@ -563,7 +572,7 @@ export function fundamentalsReportTables(
       notes: [
         ...metrics.length === 0
           ? [`No ${view} reported for ${financials.symbol}.`]
-          : trailingConversionNotes(financials.fundamentals, metrics, financials.quote?.currency),
+          : fundamentalsNotes(financials.fundamentals, metrics, financials.quote?.currency),
         ...fund ? [fund] : [],
       ],
     }),
@@ -726,7 +735,7 @@ export async function buildTickerReport({
   const metrics = fundamentalsMetrics(quote, priced.fundamentals, profile, { text: marketCapText }, priceReturns, fundamentalsCurrency(financials), { text: enterpriseValueText });
   const beforeFundamentals = lines.length;
   appendMetricSection(lines, "Fundamentals", metricLines(metrics));
-  for (const note of trailingConversionNotes(fundamentals, metrics, quote?.currency)) lines.push(cliStyles.muted(note));
+  for (const note of fundamentalsNotes(fundamentals, metrics, quote?.currency)) lines.push(cliStyles.muted(note));
   // Where a fund's facts would go: under its fundamentals, or in their place.
   const fund = fundFactsNote(quote?.symbol ?? symbol,
     quote?.tradingExchangeName || listingExchange || quote?.listingExchangeName || quote?.exchangeName || tickerFile?.metadata.exchange, financials, tickerFile);

package/src/cli/glossary.ts

@@ -351,7 +351,7 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
     term: "TTM", aliases: ["trailing twelve months", "trailing 12 months", "trailing four quarters", "ltm", "last twelve months"],
     functions: ["FA"],
     definition: "Trailing twelve months: the four latest quarters added up, a year that ends with the latest quarter rather than the fiscal year. "
-      + "FA's quarterly leverage ratios read their flows over it, and show < 4 quarters when fewer are on file.",
+      + "FA's quarterly leverage and valuation ratios (P/E, EV / EBITDA, P/S, FCF yield) read their flows over it, and show < 4 quarters when fewer are on file.",
   },
   // Funds (ETF). Named in what ETF says it cannot show yet.
   {

package/src/cli/index.ts

@@ -37,7 +37,7 @@ import { createSystemCliCommands } from "./commands/system";
 import { brokerCliCommand, ibkrCliCommand } from "./commands/broker";
 import { listPlugins, updatePlugins } from "./commands/plugins";
 import { installListedPlugin, removePlugin } from "../plugins/installer";
-import { runPaneCatalog, runPaneFunction, runPaneScreenshot } from "./pane-functions";
+import { functionCodeCommand, runPaneCatalog, runPaneFunction, runPaneScreenshot } from "./pane-functions";
 import { catalogFredSeriesIds } from "./series-search";
 
 const { width: SHOT_WIDTH, height: SHOT_HEIGHT } = SHOT_SIZE_LIMITS;
@@ -60,11 +60,11 @@ function createCoreCliCommands(
         usage: ["help [command]", "<command> --help"],
         examples: ["help", "help quote", "quote --help"],
       },
-      execute: (args, ctx) => {
+      execute: async (args, ctx) => {
         const topic = args[0];
         if (topic) {
           const command = lookupCommand(topic);
-          if (!command) failUnknownCommand(topic, allCommands());
+          if (!command) failUnknownCommand(topic, allCommands(), await functionCodeCommand(ctx, topic, []));
           printCommandHelp(command, ctx);
           return;
         }
@@ -306,7 +306,9 @@ function printCommandHelp(command: CliCommandDef, ctx: CliCommandContext): void
   ctx.printResult({ data: { ...describeCliCommand(command), sections: command.help?.sections ?? [] } });
 }
 
-function failUnknownCommand(token: string, commands: CliCommandDef[]): never {
+/** `function` is what the word is when it is a function's code, and the command that runs it. */
+function failUnknownCommand(token: string, commands: CliCommandDef[], fn: { code: string; command: string } | null = null): never {
+  if (fn) fail(`${fn.code} is a function: ${fn.command}`);
   const suggestion = suggestCliCommand(
     normalizeCliCommandToken(token),
     commands.flatMap((command) => [command.name, ...(command.aliases ?? [])]),
@@ -397,14 +399,20 @@ export async function dispatchCli(args: string[], options: DispatchCliOptions =
 /** Explains why dispatch found no command in `args`, suggesting the closest one. */
 export async function failUnknownCliCommand(args: string[], options: DispatchCliOptions = {}): Promise<never> {
   let token = args[0] ?? "";
+  let parsed: ReturnType<typeof parseCliGlobalArgs> | null = null;
   try {
     // Global flags may come first, so name the token dispatch actually looked up.
-    token = parseCliGlobalArgs(args).args[0] ?? token;
+    parsed = parseCliGlobalArgs(args);
+    token = parsed.args[0] ?? token;
   } catch {
     // dispatchCli already reported flags that do not parse.
   }
   const registry = await createRegistry(options);
-  return failUnknownCommand(token, listedCommands(registry).map((entry) => entry.command));
+  // A function's code typed as a command is pointed at `fn`, with the arguments the reader gave.
+  const fn = token && parsed
+    ? await functionCodeCommand(createCliCommandContext("core", registry, parsed.options, parsed.args.slice(1)), token, parsed.args.slice(1))
+    : null;
+  return failUnknownCommand(token, listedCommands(registry).map((entry) => entry.command), fn);
 }
 
 export async function runCli(args: string[], options: DispatchCliOptions = {}): Promise<boolean> {

package/src/cli/known-gaps.ts

@@ -82,6 +82,28 @@ export function topicPointer(query: string): { message: string; codes: string[]
   return { message: `${pointer.topic}: not in the terminal yet; closest: ${closest}`, codes: pointer.closest.map(([code]) => code) };
 }
 
+/**
+ * Settings people look for by name that are a `config` command, not a function or a ticker: the line `search` and
+ * `catalog` print beside whatever else the query finds. A query asks for one when every word is a word of that
+ * setting and one of them names it: "light theme", "dark", "colour-blind", but not "ai theme" (THEM's basket) or
+ * "dark pool".
+ */
+const SETTING_POINTERS: ReadonlyArray<{ names: readonly string[]; words: readonly string[]; line: string }> = [
+  {
+    names: ["theme", "themes", "light", "dark", "colorblind", "colourblind", "blind"],
+    words: ["mode", "color", "colour", "colors", "colours", "high", "contrast", "change", "switch", "set", "setting", "settings"],
+    line: "Themes: gloomberb config themes",
+  },
+];
+
+/** The `config` command for a query that names a setting ("light theme"), else null. */
+export function settingsPointer(query: string): string | null {
+  const asked = words(query);
+  if (asked.length === 0) return null;
+  return SETTING_POINTERS.find(({ names, words: other }) => asked.some((word) => names.includes(word))
+    && asked.every((word) => names.includes(word) || other.includes(word)))?.line ?? null;
+}
+
 /** Letters and digits only, lower case: `EU-ETS`, `eu ets` and `EUETS` are one lookup. */
 function lookupKey(text: string): string {
   return text.toLowerCase().replace(/[^a-z0-9]/g, "");

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

@@ -115,6 +115,43 @@ export function buildPaneFunctionLookup(registry: PaneFunctionCatalog): Map<stri
   return lookup;
 }
 
+/** What a function takes after its code, as the catalog writes it: `<ticker>`, `<fund, ticker, or CIK>`, or nothing. */
+function argumentHint({ argKind, argPlaceholder }: Pick<PaneCatalogEntry, "argKind" | "argPlaceholder">): string {
+  if (argPlaceholder) return `<${argPlaceholder}>`;
+  return argKind && argKind !== "none" ? `<${argKind}>` : "";
+}
+
+/** A command-line token that is the code or an alias of a function, with what the function takes. */
+export interface FunctionCode {
+  argument: string;
+}
+
+/**
+ * Whether `token` is the code or an alias of a function (`OVDV`, `EEO`), in any
+ * case: the function `fn` opens for it, not one it merely matches by a keyword
+ * or a label.
+ */
+export function findFunctionCode(registry: PaneFunctionCatalog, token: string): FunctionCode | null {
+  const wanted = normalizeLookupToken(token);
+  const found = wanted ? buildPaneFunctionLookup(registry).get(wanted) : undefined;
+  if (!found || !("paneId" in found && "description" in found)) return null;
+  const pane = registry.panes.get(found.paneId);
+  const headless = pane ? getHeadlessPaneDefinition(found, pane) : undefined;
+  const codes = [
+    found.shortcut?.prefix,
+    ...(found.shortcut?.aliases ?? []),
+    headless?.discovery?.id,
+    ...(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,
+    }),
+  };
+}
+
 function sampleArgForTemplate(template: PaneTemplateDef): string {
   switch (template.shortcut?.argKind) {
     case "ticker":
@@ -438,11 +475,6 @@ function readinessCell(readiness: PaneFunctionReadiness): string {
   return cliStyles.muted(label);
 }
 
-function catalogArgument(entry: PaneCatalogEntry): string {
-  if (entry.argPlaceholder) return `<${entry.argPlaceholder}>`;
-  return entry.argKind && entry.argKind !== "none" ? `<${entry.argKind}>` : "";
-}
-
 // Choices longer than this move from the flag into its description, where they can wrap.
 const MAX_INLINE_CHOICES = 24;
 
@@ -473,7 +505,7 @@ export function limitationSentence(text: string): string {
 function renderCatalogEntry(entry: PaneCatalogEntry): string {
   const width = Math.min(cliTerminalWidth() ?? CATALOG_TEXT_WIDTH, CATALOG_TEXT_WIDTH);
   const capability = entry.capability;
-  const argument = catalogArgument(entry);
+  const argument = argumentHint(entry);
   const invocation = `${entry.token}${argument ? ` ${argument}` : ""}`;
   const lines = [
     `${cliStyles.accent(entry.token)}  ${cliStyles.bold(entry.label)}`,
@@ -543,25 +575,28 @@ export function renderPaneCatalogReport(
   glossary: GlossaryLookup = { exact: [], partial: [] },
   gap: string | null = null,
   series: readonly SeriesMatch[] = [],
+  /** The `config` command a query names a setting of ("light theme"), printed last, beside the functions. */
+  setting: string | null = null,
 ): string {
   const query = args.query.trim().toLowerCase();
   const exact = query
     ? entries.find((entry) => entry.token.toLowerCase() === query)
       ?? entries.find((entry) => entry.aliases.some((alias) => alias.toLowerCase() === query))
     : undefined;
-  if (exact) return renderCatalogEntry(exact);
+  const withSetting = (text: string) => [text, setting ?? ""].filter(Boolean).join("\n\n");
+  if (exact) return withSetting(renderCatalogEntry(exact));
 
   const width = Math.min(cliTerminalWidth() ?? CATALOG_TEXT_WIDTH, CATALOG_TEXT_WIDTH);
   const terms = renderCatalogGlossary(glossary, width);
   const charted = renderSeriesMatches(args.query.trim(), series, Number.isFinite(args.limit) ? CATALOG_SERIES_LIMIT : series.length, width);
-  const withGap = (text: string) => [gap ? wrapText(gap, width).join("\n") : "", text].filter(Boolean).join("\n\n");
+  const withGap = (text: string) => withSetting([gap ? wrapText(gap, width).join("\n") : "", text].filter(Boolean).join("\n\n"));
   const withTerms = (text: string) => withGap([text, charted, terms].filter(Boolean).join("\n\n"));
   if (args.query && entries.length === 1) return withTerms(renderCatalogEntry(entries[0]!));
 
   const note = (text: string) => wrapText(text, width).map((line) => cliStyles.muted(line)).join("\n");
   if (entries.length === 0) {
     if (charted) return withGap([charted, terms].filter(Boolean).join("\n\n"));
-    if (glossary.exact.length > 0 || gap) return withGap(terms);
+    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 are available."));
@@ -586,7 +621,7 @@ export function renderPaneCatalogReport(
       shown.map((entry) => [
         cliStyles.command(entry.token),
         entry.label,
-        catalogArgument(entry),
+        argumentHint(entry),
         readinessCell(entry.capability.reportReadiness),
         entry.description,
       ]),

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

@@ -1,34 +1,39 @@
 import type { DesktopPaneShotRenderedRow } from "../desktop-pane-shot";
-import { cliStyles, cliTerminalWidth, renderSection, renderTable, wrapText } from "../../utils/cli-output";
+import { cliStyles, renderSection, renderTable } from "../../utils/cli-output";
 import { formatUtcTime } from "../../utils/utc-time";
 import type { MarketContext } from "../types";
 import type { PaneFunctionReport } from "./report";
 import type { ResolvedPaneFunction } from "./resolver";
 import { collectShotSymbols } from "./data";
+import { lockNoteLines } from "./lock-note";
+import { lockNoteReason } from "../../plugins/builtin/shared/pro-lock-note";
 import { renderDesktopShot, type PaneScreenshotResult } from "./screenshot";
 import { deriveRenderedFreshness, formatFreshnessLine, type ReportFreshness } from "./freshness";
 import { exportTextTable, reportFooterLines, type CliReportTables } from "../report-tables";
-import { renderedReportFreshness, renderedReportNotices, renderedReportObservations } from "./report-notices";
+import { renderedReportFailure, renderedReportFreshness, renderedReportNotices, renderedReportObservations } from "./report-notices";
 
 const DOM_REPORT_WIDTH = 1280;
 const DOM_REPORT_HEIGHT = 720;
 const DOM_LIMITATION =
   "Only values visible in the rendered pane are returned; clipped or off-screen data may be omitted.";
-/** The widest a lock note wraps to, as the catalog's text. */
-const LOCK_NOTE_WIDTH = 100;
 const DOM_EVERY_ROW =
   "Every row of the pane's table is returned, including rows scrolled out of view.";
 
 /** The sign-in wall's buttons, which a rendered view reads as words: `Log in ↵ Sign up free`. */
 const SIGN_IN_WALL_BUTTONS = /\s*\b(?:Log in|Sign up free|Resend Verification Email)(?:\s*\u21B5)?(?=\s|$)/g;
 
+/** Whether the wall asks for the account's email to be verified, not for a sign-in. */
+function asksToVerifyEmail(visibleText: string): boolean {
+  return /\bVerify your email\b/i.test(visibleText);
+}
+
 /**
  * A pane behind the sign-in wall, as a report reads it: the wall's headline
  * without its buttons, and what it needs in place of them.
  */
 function signInWallText(visibleText: string): string {
   const headline = visibleText.replace(SIGN_IN_WALL_BUTTONS, "").trim();
-  const needs = /\bVerify your email\b/i.test(visibleText)
+  const needs = asksToVerifyEmail(visibleText)
     ? "Requires a verified email on your Gloom account; resend the verification email in the app."
     : "Requires a free Gloom sign-in: log in or sign up in the app.";
   return headline ? `${headline} ${needs}` : needs;
@@ -195,14 +200,20 @@ export function buildDomPaneReportFromRender(
   // A wall in place of the whole pane: nothing was read, so the report says
   // 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?.({ gate, symbol: result.symbols[0] ?? null }) ?? null : null;
+  const lockNote = gate
+    ? resolved.pane.reportLockNote?.({
+      gate,
+      symbol: result.symbols[0] ?? null,
+      token: resolved.token,
+      ...gate === "sign-in" && asksToVerifyEmail(result.render.visibleText ?? "") ? { verifyEmail: true } : {},
+    }) ?? null
+    : null;
   const locked = gate === "sign-in" || lockNote ? gate : null;
-  // JSON and CSV say why the report is empty in the note's words, on one line.
-  const lockReason = lockNote?.replace(/\s*\n\s*/g, " ") ?? null;
+  const lockReason = lockNote ? lockNoteReason(lockNote) : null;
   if (hasStructuredRows) {
     textLines.push(...renderDomTables(rows));
   } else if (lockNote) {
-    textLines.push(...wrapText(lockNote, Math.min(cliTerminalWidth() ?? LOCK_NOTE_WIDTH, LOCK_NOTE_WIDTH)));
+    textLines.push(...lockNoteLines(lockNote));
   } else if (result.render.visibleText) {
     textLines.push(gate === "sign-in" ? signInWallText(result.render.visibleText) : result.render.visibleText);
   } else {
@@ -321,13 +332,21 @@ function failedDomReport(
   };
 }
 
+/** A report the rendered pane says it cannot give; the command fails with the pane's words and advice line. */
+class RenderedReportFailure extends Error {
+  constructor(message: string, readonly details?: string) {
+    super(message);
+  }
+}
+
 export async function buildDomFunctionReport(
   resolved: ResolvedPaneFunction,
   context: MarketContext,
   rawArg: string,
 ): Promise<PaneFunctionReport> {
+  let result: PaneScreenshotResult;
   try {
-    const result = await renderDesktopShot({
+    result = await renderDesktopShot({
       resolved,
       context,
       rawArg,
@@ -340,6 +359,13 @@ export async function buildDomFunctionReport(
       options: {},
       captureImage: false,
     });
+  } catch (error) {
+    return failedDomReport(resolved, rawArg, error);
+  }
+  // No header and no partial view: the error alone, and a failed exit, as the plain command gives.
+  const failure = renderedReportFailure(result.render.semanticUi ?? []);
+  if (failure) throw new RenderedReportFailure(failure.message, failure.details);
+  try {
     return buildDomPaneReportFromRender(resolved, result);
   } catch (error) {
     return failedDomReport(resolved, rawArg, error);

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

@@ -264,8 +264,10 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
   },
   OSA: {
     summary: "Build a multi-leg options position and value it at any spot, date and vol shift: payoff, P&L grid, breakevens and Greeks. European pricing, so no early exercise. "
-      + "With a NAV and a budget in bps it sizes the position as a hedge: contracts, premium, notional protected and coverage of an equity sleeve.",
+      + "With a NAV and a budget in bps it sizes the position as a hedge: contracts, premium, notional protected and coverage of an equity sleeve. "
+      + "--strategy csp sells a cash-secured put: cash secured, premium, yield on cash and annualised, distance out of the money, break-even, days to expiry and an earnings flag.",
     usage: ["OSA AAPL", "gloomberb fn OSA AAPL --strategy vertical --expiration 2027-01-15",
+      "gloomberb fn OSA KO --strategy csp --strike 85 --expiration 2026-11-20",
       "gloomberb fn OSA SPY --strategy put --strike 700 --expiration 2027-01-15 --nav 100m --budget-bps 50 --sleeve 100m"],
     keys: [key("a", "dd leg"), key("c", "hain"), key("d", "ate"), key("v", "ol shift")],
     data: OPTIONS,
@@ -393,7 +395,7 @@ export const FUNCTION_HELP: Readonly<Record<string, FunctionHelp>> = {
     bloomberg: ["ERN"],
   },
   DVD: {
-    summary: "Cash distributions, trailing yield, the forward yield fundamentals show (latest distribution annualized), and payout growth. Future payments are not forecast.",
+    summary: "Cash distributions, trailing yield, the forward yield fundamentals show (the latest distribution annualized, or the declared one once announced), and payout growth. Future payments are not forecast.",
     usage: ["DVD KO"],
     keys: [STEP],
     data: same("Daily"),

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

@@ -40,6 +40,7 @@ import { isRecord } from "../../utils/guards";
 import { formatUtcTime, localTimeSuffix } from "../../utils/utc-time";
 import { deriveHeadlessFreshness, formatFreshnessLine, staleRowsText, type ReportFreshness } from "./freshness";
 import { accessGateStatus, errorsAccessGate, isProLock } from "./access-gate";
+import { lockedHeadlessReport } from "./lock-note";
 
 interface SerializableHeadlessColumn {
   key: string;
@@ -721,7 +722,17 @@ export async function buildHeadlessFunctionReport(
   context: MarketContext,
   rawArgument: string,
 ): Promise<PaneFunctionReport> {
-  const loaded = await loadResolvedHeadlessPaneModel(resolved, context, rawArgument);
+  let loaded: LoadedHeadlessPaneModel;
+  try {
+    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, () => (
+      buildHeadlessPaneLoadArgs(resolved.headless!, resolved.token, rawArgument, resolved.options).symbols
+    ));
+    if (locked) return locked;
+    throw error;
+  }
   const { complete, unavailableSymbols, rowCount, symbols } = reportCoverage(loaded);
   const serialized = serializeHeadlessPaneResult(loaded.definition, loaded.result);
   const freshness = deriveHeadlessFreshness(loaded.definition, loaded.result);

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

@@ -5,6 +5,7 @@ import { withMarketData } from "../context";
 import { cliStyles, renderStats, type CliStatEntry } from "../../utils/cli-output";
 import {
   filterPaneCatalogEntries,
+  findFunctionCode,
   renderPaneCatalogReport,
   selectPaneCatalogMatches,
   type PaneFunctionCatalog,
@@ -25,7 +26,7 @@ import {
 import { incompleteReportGateMessage } from "./access-gate";
 import { withPersistedCloudSession } from "./cloud-session";
 import { ListingArgError, listingReadNotes, loadForListing, quotedListingChoiceNotes } from "../listing-arg";
-import { knownGapMessage, topicPointer } from "../known-gaps";
+import { knownGapMessage, settingsPointer, topicPointer } from "../known-gaps";
 import { selectReportTables } from "../report-tables";
 import { cliOutputWritten } from "../result";
 import { CLI_EXIT_CODES } from "../exit-codes";
@@ -63,6 +64,44 @@ async function withPaneRuntime<T>(
   });
 }
 
+/** A word that can be a function code: letters and digits, with the dots and dashes some codes carry. */
+const FUNCTION_CODE_WORD = /^[\w.$-]{1,24}$/;
+
+/** An argument as a shell reads it back: bare when it is one word, in quotes when it is not. */
+function commandWord(argument: string): string {
+  return /^[\w.:,=%+@/-]+$/.test(argument) ? argument : JSON.stringify(argument);
+}
+
+/**
+ * What to run when a command name is a function's code (`gloomberb OVDV KO`,
+ * `gloomberb help OVDV`): `fn` with the reader's own arguments, or the
+ * function's argument hint when they gave none. Null when the word is no
+ * function code or the catalog cannot be read, and the command stays unknown.
+ */
+export async function functionCodeCommand(
+  ctx: CliCommandContext,
+  token: string,
+  args: readonly string[],
+): Promise<{ code: string; command: string } | null> {
+  const word = token.trim();
+  if (!FUNCTION_CODE_WORD.test(word)) return null;
+  try {
+    const found = await withMarketData(ctx, async (market) => {
+      const registry = await createPaneCatalog(market, ctx.plugins);
+      try {
+        return findFunctionCode(registry, word);
+      } finally {
+        registry.destroy();
+      }
+    });
+    if (!found) return null;
+    const code = word.replace(/^\$/, "").toUpperCase();
+    return { code, command: ["gloomberb fn", code, args.length > 0 ? args.map(commandWord).join(" ") : found.argument].filter(Boolean).join(" ") };
+  } catch {
+    return null;
+  }
+}
+
 export async function runPaneFunction(args: string[], ctx: CliCommandContext) {
   await runPaneCliCommand(ctx, async () => {
     await withPaneRuntime(ctx, args, async ({ parsed, context, resolved }) => {
@@ -277,6 +316,8 @@ export async function runPaneCatalog(args: string[], ctx: CliCommandContext) {
         const glossary = lookupGlossary(parsed.query);
         // Data no source carries yet is said once: in the text, else as the envelope's warning.
         const gap = knownGapMessage(parsed.query);
+        // A setting is a command, not a function: "light theme" names `config themes` beside THEM.
+        const setting = settingsPointer(parsed.query);
         // The data catalog series the query names, which `fn G` charts.
         const series = findCatalogSeries(ctx.plugins, parsed.query);
         const listed = pointer
@@ -285,9 +326,9 @@ export async function runPaneCatalog(args: string[], ctx: CliCommandContext) {
         ctx.printResult({
           data: listed,
           ...series.length ? { metadata: { series } } : {},
-          ...gap && ctx.cliOptions.format !== "text" ? { warnings: [gap] } : {},
+          ...(gap || setting) && ctx.cliOptions.format !== "text" ? { warnings: [gap, setting].filter((note): note is string => !!note) } : {},
         }, {
-          text: () => renderPaneCatalogReport(filtered, effectiveParsed, glossary, gap, series),
+          text: () => renderPaneCatalogReport(filtered, effectiveParsed, glossary, gap, series, setting),
         });
       } finally {
         registry.destroy();

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

@@ -0,0 +1,56 @@
+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 { PaneFunctionReport } from "./report";
+import type { ResolvedPaneFunction } from "./resolver";
+
+/** The widest a lock note wraps to, as the catalog's text. */
+const LOCK_NOTE_WIDTH = 100;
+
+/** The closing line of a headless report whose pane was walled whole, as a rendered view's says it. */
+const LOCKED_VIEW_NOTE = "The pane is locked, so no values were read.";
+
+/** A pane's `reportLockNote`, wrapped for the text report. */
+export function lockNoteLines(note: string): string[] {
+  return wrapText(note, Math.min(cliTerminalWidth() ?? LOCK_NOTE_WIDTH, LOCK_NOTE_WIDTH));
+}
+
+/**
+ * What a headless report prints when the server refused its read behind a
+ * wall, as the rendered view of the same pane prints that wall: the pane's
+ * `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.
+ */
+export 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 {
+  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 reason = lockNoteReason(note);
+  return {
+    data: {
+      kind: resolved.headless?.shape ?? "rendered-view",
+      target: resolved.token,
+      capabilityId: resolved.capability.id,
+      symbols,
+      options: resolved.options,
+      rowCount: 0,
+      empty: true,
+      complete: false,
+      unavailableSymbols: symbols,
+      reason,
+      locked: gate,
+    },
+    text: [resolved.label, "", ...lockNoteLines(note), "", LOCKED_VIEW_NOTE].join("\n"),
+    tables: { tables: [], footer: reportFooterLines({ incomplete: reason, notes: [LOCKED_VIEW_NOTE] }) },
+  };
+}