gloomberb 0.18.1 → 0.18.2

package/src/cli/glossary.ts

@@ -2,7 +2,7 @@ import { cliStyles, cliTerminalWidth, renderDefinitions, renderSection, wrapText
 
 /**
  * Plain-words meanings of the rates, auction, credit and bond yield, energy, perpetual-futures, portfolio,
- * fund, bond fund (SEC yield, tax-equivalent yield, muni/Treasury ratio), short interest, quote-board, futures (basis, contango, roll yield), VIX curve (term structure, 3M/30D, VVIX) and economic-calendar terms the functions
+ * fund, bond fund (SEC yield, tax-equivalent yield, muni/Treasury ratio), short interest, quote-board, futures (basis, contango, roll yield), VIX curve (term structure, 3M/30D, VVIX), CFTC positioning (COT trader classes, net % of open interest) and economic-calendar terms the functions
  * show in their rows, headers and footers.
  * `catalog glossary` lists them, `catalog explain <term>` prints one, and
  * `fn <function> --explain` and `portfolio show --explain` follow a report with
@@ -242,7 +242,7 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
     definition: "The first date the new rate level appears in the data, not necessarily the announcement or effective date.",
   },
   {
-    term: "Pctl 1Y", aliases: ["percentile", "1y percentile", "pctl"], functions: ["BTMM", "WIRP", "CBR", "CDX", "SOVR"],
+    term: "Pctl 1Y", aliases: ["percentile", "1y percentile", "1-year percentile", "pctl"], functions: ["BTMM", "WIRP", "CBR", "CDX", "SOVR", "COT"],
     definition: "Where today's value ranks against the past year of the same series: 100 is the highest, 0 the lowest.",
   },
   {
@@ -360,8 +360,8 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
       + "a simple annualisation of the rate now, not funding actually paid.",
   },
   {
-    term: "Open interest", short: "OI", aliases: ["open interest usd"], functions: ["PERP"],
-    definition: "The total value of contracts that are open and not yet closed, counting each buyer and seller pair once, usually in dollars. "
+    term: "Open interest", short: "OI", aliases: ["open interest usd"], functions: ["PERP", "COT"],
+    definition: "The contracts that are open and not yet closed, counting each buyer and seller pair once: COT counts them, PERP gives their value, usually in dollars. "
       + "It rises as new positions open and falls as they close.",
   },
   {
@@ -631,6 +631,59 @@ export const GLOSSARY: readonly GlossaryEntry[] = [
     definition: "A futures contract's official price for the day, set by its exchange from trading near the close. "
       + "The day's change and margin are measured from it, and it can differ from the last trade. FUT's PREV is the previous one.",
   },
+  // CFTC positioning (COT): the legacy report's trader classes, then the disaggregated report's.
+  {
+    term: "Commitments of Traders", short: "COT", aliases: ["cot report", "commitment of traders", "cftc", "cftc report", "cftc positioning", "positioning"],
+    functions: ["COT"], shown: ["CFTC", "COT"],
+    definition: "The CFTC's weekly count of who holds each US futures market: open contracts split by type of trader, as of Tuesday and published that Friday. "
+      + "It shows whether speculators or hedgers are net long or short, and how that moved since the week before.",
+  },
+  {
+    term: "Noncommercial", aliases: ["non-commercial", "noncommercials", "large speculators", "speculators", "large specs"], functions: ["COT"],
+    definition: "Large traders who do not hedge a business with the contract, such as funds and other speculators. "
+      + "Their net position is the one most often read as the market's bet.",
+  },
+  {
+    term: "Commercial", aliases: ["commercials", "hedgers", "commercial hedgers"], functions: ["COT"],
+    definition: "Large traders who use the contract to hedge a business: producers, processors, merchants and dealers. "
+      + "In a commodity they are usually net short, selling ahead what they will grow, mine or deliver.",
+  },
+  {
+    term: "Nonreportable", aliases: ["non-reportable", "nonreportables", "small traders", "small speculators"], functions: ["COT"],
+    definition: "Traders too small to report their positions to the CFTC, counted as open interest less every reported position. Mostly smaller speculators.",
+  },
+  {
+    term: "Net position", short: "Net", aliases: ["net long", "net short", "net positioning", "net spec"], functions: ["COT"], shown: ["Net"],
+    definition: "A group's long contracts less its short ones: positive is net long, negative net short.",
+  },
+  {
+    term: "Net % of open interest", short: "Net % OI", aliases: ["% of open interest", "percent of open interest", "net percent of open interest"], functions: ["COT"],
+    definition: "A group's net position as a share of all open contracts, so markets of different sizes compare: +8.3% means its longs exceed its shorts by 8.3% of open interest.",
+  },
+  {
+    term: "Weekly change", short: "1W Δ", aliases: ["1w change", "week change", "weekly net change"], functions: ["COT"],
+    definition: "How far a group's net position moved since the previous weekly report, in contracts.",
+  },
+  {
+    term: "Pctl 3Y", aliases: ["3y percentile", "3-year percentile", "three-year percentile"], functions: ["COT"],
+    definition: "Where this week's net position ranks against the past three years of weekly reports: 100 is the most net long it has been, 0 the most net short.",
+  },
+  {
+    term: "Managed money", aliases: ["money managers", "managed money traders", "hedge funds", "ctas"], functions: ["COT"], shown: ["Managed Money"],
+    definition: "The disaggregated report's funds that trade futures for clients, such as hedge funds and CTAs: the speculators most often watched.",
+  },
+  {
+    term: "Producer/merchant", aliases: ["producers", "merchants", "producer merchant", "processors"], functions: ["COT"], shown: ["Producer/Merchant"],
+    definition: "The disaggregated report's growers, miners, processors and merchants that hedge the physical commodity they produce or handle.",
+  },
+  {
+    term: "Swap dealers", aliases: ["swap dealer", "swaps dealers"], functions: ["COT"], shown: ["Swap Dealers"],
+    definition: "The disaggregated report's banks and dealers that hedge the commodity swaps they sell to clients, often index investors.",
+  },
+  {
+    term: "Other reportables", aliases: ["other reportable", "other reportable traders"], functions: ["COT"], shown: ["Other Reportables"],
+    definition: "The disaggregated report's large traders that fit none of its other classes, such as proprietary traders and family offices.",
+  },
   // Futures basis and curve shape (CTM, FUT, PERP).
   {
     term: "Futures basis", aliases: ["basis", "basis trade", "cash and carry", "cash-and-carry", "vs spot", "spot spread"],

package/src/cli/helpers.ts

@@ -1,10 +1,15 @@
 import {
   formatCompact,
   formatCurrency,
+  formatCurrencyCode,
   formatNumber,
   formatPercentRaw,
 } from "../utils/format";
-import { formatMarketPriceWithCurrency, type MarketFormatOptions } from "../market-data/market/format";
+import { formatMarketChangeWithCurrency, formatMarketPriceWithCurrency, type MarketFormatOptions } from "../market-data/market/format";
+import { changeBasisLabel, changeBasisNote, quoteChangeBasis } from "../market-data/market/change-basis";
+import type { FuturesContractTermsPayload } from "../api-client/futures-curve";
+import type { ActiveQuoteDisplay } from "../market-data/market/status";
+import type { Quote } from "../types/financials";
 import { cliStyles, colorBySign } from "../utils/cli-output";
 import type { AppConfig } from "../types/config";
 import type { Watchlist, TickerRecord } from "../types/ticker";
@@ -12,8 +17,36 @@ import { isFiniteNumber } from "../utils/guards";
 import { formatUtcTime } from "../utils/utc-time";
 import { findNamedCollection } from "../portfolio/collection-name";
 
-export function formatSignedCurrency(value: number, currency: string): string {
-  return value > 0 ? `+${formatCurrency(value, currency)}` : formatCurrency(value, currency);
+/** A signed amount with its sign ($), or with `code` its code (+12.50 CAD) as a report for another base currency writes it. */
+export function formatSignedCurrency(value: number, currency: string, code = false): string {
+  const text = (code ? formatCurrencyCode : formatCurrency)(value, currency);
+  return value > 0 ? `+${text}` : text;
+}
+
+/**
+ * The Change line of `ticker` and of `quote`'s futures block: the regular
+ * session's move and its percent, colored by sign, and what the move is
+ * measured from, "-HK$0.10 (-1.05%) vs Fri 16 Oct close" (a future's from
+ * its terms, "vs Fri 16 Oct settle"), with the venue's holidays since that
+ * close on the line under it ("HKEX closed Mon 19 Oct, holiday").
+ */
+export function quoteChangeText(
+  quote: Quote,
+  session: Pick<ActiveQuoteDisplay, "price" | "change" | "changePercent">,
+  options: MarketFormatOptions,
+  terms?: Pick<FuturesContractTermsPayload, "settlement" | "spec"> | null,
+  now = Date.now(),
+): string {
+  // A listing that no longer trades: its last close moves no more.
+  if (quote.delisting) return "—";
+  const move = colorBySign(
+    `${formatMarketChangeWithCurrency(session.change, quote.currency ?? "USD", options, session.price)} (${formatPercentRaw(session.changePercent)})`,
+    session.change,
+  );
+  const basis = quoteChangeBasis(quote, { terms });
+  if (!basis) return move;
+  const note = changeBasisNote(basis, now);
+  return `${move} ${cliStyles.muted(changeBasisLabel(basis, now))}${note ? `\n${cliStyles.muted(note)}` : ""}`;
 }
 
 // Text-table cell formats. They leave missing values blank; CSV and JSON keep the raw numbers.

package/src/cli/index.ts

@@ -47,6 +47,7 @@ import {
   runPaneScreenshot,
 } from "./pane-functions";
 import { catalogPointer, tickerPointer, type CatalogCommandHit } from "./unknown-command";
+import { exportCommandPointer } from "./known-gaps";
 import { catalogFredSeriesIds } from "./series-search";
 import { primeBoardCoins } from "./board-coins";
 
@@ -382,7 +383,9 @@ function failUnknownCommand(token: string, commands: CliCommandDef[], pointers:
       [`Run: ${pointers.nearFn.command}`, ticker].filter(Boolean).join("\n"),
     );
   }
-  const catalog = suggestion ? null : catalogPointer(token, pointers.hits, pointers.args);
+  // Exporting is a flag, not a command: `export LMT` says how, rather than listing functions that mention exports.
+  const exported = suggestion ? null : exportCommandPointer(token, pointers.args);
+  const catalog = suggestion ? null : exported ?? catalogPointer(token, pointers.hits, pointers.args);
   const help = suggestion
     ? `Did you mean ${suggestion}? Run gloomberb help to see every command.`
     : catalog ? `${catalog}\nRun gloomberb help to see every command.` : "Run gloomberb help to see every command.";

package/src/cli/known-gaps.ts

@@ -109,6 +109,23 @@ const BANK_FIGURES_TOPIC = {
   closest: [["EQS", "NIM%, Pro: gloomberb fn EQS --metric kpiNimPercent"]],
 } as const;
 
+/**
+ * How to export: a flag on every command, which `export LMT`, `catalog export` and `catalog csv` look for as a
+ * command or a function. One example, writing a file.
+ */
+function exportLine(symbol = "LMT"): string {
+  return `Export: add --csv or --json to any command to print its result as CSV or JSON, e.g. gloomberb history ${symbol} --csv > ${
+    symbol.toLowerCase().replace(/[^a-z0-9]+/g, "-")}.csv`;
+}
+
+const EXPORT_POINTER = {
+  names: ["export", "exporting", "csv", "json", "excel", "spreadsheet", "xlsx"],
+  words: ["data", "to", "as", "a", "an", "the", "in", "into", "file", "files", "table", "tables", "result", "results", "output",
+    "format", "save", "how", "can", "i", "my", "report", "reports", "command", "commands"],
+  line: exportLine(),
+  leads: true,
+} as const;
+
 /** "bank", "bank figures": beside the functions a bank's name finds (CBR), where its figures are. */
 const BANK_FIGURES_POINTER = {
   names: ["bank", "banks", "banking"],
@@ -193,8 +210,9 @@ export function topicPointer(query: string): { message: string; codes: string[]
  * "dark pool"; "drip", "dividend income", but not "income statement" or "net income"; "tether", "depeg",
  * "usdc peg", but not "peg ratio".
  */
-const COMMAND_POINTERS: ReadonlyArray<{ names: readonly string[]; words: readonly string[]; line: string }> = [
+const COMMAND_POINTERS: ReadonlyArray<{ names: readonly string[]; words: readonly string[]; line: string; leads?: true }> = [
   BANK_FIGURES_POINTER,
+  EXPORT_POINTER,
   {
     names: ["theme", "themes", "light", "dark", "colorblind", "colourblind", "blind"],
     words: ["mode", "color", "colour", "colors", "colours", "high", "contrast", "change", "switch", "set", "setting", "settings"],
@@ -218,6 +236,24 @@ export function commandPointer(query: string): string | null {
   return findCommandPointer(query)?.line ?? null;
 }
 
+/**
+ * Whether the query's command line answers it ahead of the functions its words find: "csv" is the flag, not
+ * CDS, whose description happens to mention it.
+ */
+export function commandPointerLeads(query: string): boolean {
+  return findCommandPointer(query)?.leads === true;
+}
+
+/**
+ * The line for a command word typed as `gloomberb export LMT`: exporting is a flag every command takes, not a
+ * command, so the example runs on the symbol typed. Null for any other word.
+ */
+export function exportCommandPointer(token: string, args: readonly string[]): string | null {
+  if (findCommandPointer(token) !== EXPORT_POINTER) return null;
+  const symbol = args.find((arg) => /^\^?[A-Z0-9][A-Z0-9.=-]{0,11}(?::[A-Z0-9]{1,8})?$/.test(arg) && /[A-Z]/.test(arg));
+  return exportLine(symbol);
+}
+
 function findCommandPointer(query: string): (typeof COMMAND_POINTERS)[number] | null {
   const asked = words(query);
   if (asked.length === 0) return null;

package/src/cli/listing-arg.ts

@@ -42,6 +42,7 @@ import { classifyInstrumentType, kindFromListingSyntax } from "../tickers/instru
 import type { InstrumentOfKind } from "../tickers/instrument-coverage";
 import { brokerIndexCode, brokerIndexReadAs } from "./index-roots";
 import { readTerminalListingCode, terminalCodeReadAs } from "../tickers/terminal-codes";
+import { listingAbroadVenue } from "../utils/sec";
 
 /** The `--exchange` option of every command that takes a ticker. */
 export const EXCHANGE_OPTION = {
@@ -342,7 +343,7 @@ export function listingChoiceNote(
 }
 
 // Quotes of these never name a company's listing, so they are never a choice between companies.
-const UNLISTED_TYPES = new Set(["FUTURE", "INDEX", "CURRENCY", "CRYPTOCURRENCY", "OPTION"]);
+export const UNLISTED_TYPES = new Set(["FUTURE", "INDEX", "CURRENCY", "CRYPTOCURRENCY", "OPTION"]);
 
 /** Whether the data service chose the listing: a bare symbol, with no venue named and none saved. */
 function isBareListing(listing: Pick<CliListing, "exchange" | "saved">): boolean {
@@ -860,11 +861,43 @@ async function builderDexMarket(listing: ListingArg, deps: ListingDeps): Promise
     : null;
 }
 
+/** A symbol written with a venue's suffix, as data vendors write a listing abroad: RY.TO, 7203.T, VOD.L, 0700.HK. */
+const VENUE_SUFFIX = /^([A-Z0-9][A-Z0-9&-]*)\.([A-Z]{1,3})$/;
+
+/**
+ * RY.TO, 7203.T, VOD.L: a listing abroad written with a data vendor's venue
+ * suffix, read as the listing its own quote names (RY:TSX, 7203:JPX,
+ * VOD:LSE), the way `quote` names it, so data that is read by venue (a
+ * company's SEC filings, data that covers US listings only) finds the same
+ * listing the quote is for. A US share class (BRK.B, quoted on NYSE), a
+ * suffix no quote answers and a named venue stay as typed.
+ */
+async function readVenueSuffix(listing: ListingArg, deps: Pick<ListingDeps, "dataProvider">): Promise<ListingArg | null> {
+  const match = listing.exchange ? null : VENUE_SUFFIX.exec(listing.symbol);
+  if (!match) return null;
+  let quote: Quote | null;
+  try {
+    quote = await deps.dataProvider.getQuote(listing.symbol, "");
+  } catch (error) {
+    // The command's own request then says what is wrong with the symbol.
+    if (!isNoProviderError(error)) logFailure("cli.listing-arg", "Quote venue suffix failed")(error);
+    return null;
+  }
+  const venue = canonicalExchange(quote?.listingExchangeName || quote?.exchangeName);
+  const key = `${match[1]}:${venue}`;
+  if (!venue || !isKnownExchangeCode(venue) || !listingAbroadVenue(key)) return null;
+  return { symbol: match[1]!, exchange: venue, key, readAs: `Read ${listing.symbol} as ${key}.` };
+}
+
 export async function resolveCliListing(
   raw: string,
   exchangeOption: string | null | undefined,
   deps: ListingDeps,
-  options: { ownExchangeWins?: boolean } = {},
+  options: {
+    ownExchangeWins?: boolean;
+    /** Read a venue suffix (RY.TO) as the listing its quote names (RY:TSX): `fn` and `shot`, whose functions read data by venue. */
+    venueSuffix?: boolean;
+  } = {},
 ): Promise<CliListing> {
   // "JPM US Equity" is Bloomberg's code for JPM; "Putnam US Equity", whose root is no US ticker, is a name.
   const typed = stripStrayEdges(raw).text || raw;
@@ -879,6 +912,8 @@ export async function resolveCliListing(
   // USD-NGN and USDNGN are the pair USDNGN=X unless a security is listed under those letters.
   const pair = parsed.exchange ? null : await readAmbiguousCurrencyPair(parsed.symbol, deps);
   if (pair) parsed = { symbol: pair, exchange: "", key: pair };
+  const suffixed = pair || named || !options.venueSuffix ? null : await readVenueSuffix(parsed, deps);
+  if (suffixed) parsed = parsed.readAs ? { ...suffixed, readAs: `${parsed.readAs} ${suffixed.readAs}` } : suffixed;
   try {
     await checkListingExchange(parsed, deps);
   } catch (error) {

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

@@ -694,13 +694,15 @@ export function renderPaneCatalogReport(
   series: readonly SeriesMatch[] = [],
   /** The `config` command a query names a setting of ("light theme"), printed last, beside the functions. */
   setting: string | null = null,
+  /** The setting answers the query ahead of the functions its words find (`csv` is the flag, not CDS): printed first. */
+  settingFirst = false,
 ): 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;
-  const withSetting = (text: string) => [text, setting ?? ""].filter(Boolean).join("\n\n");
+  const withSetting = (text: string) => (settingFirst ? [setting ?? "", text] : [text, setting ?? ""]).filter(Boolean).join("\n\n");
   if (exact) return withSetting([renderCatalogEntry(exact), renderAlsoMatches(exact, entries, query)].filter(Boolean).join("\n\n"));
 
   const width = Math.min(cliTerminalWidth() ?? CATALOG_TEXT_WIDTH, CATALOG_TEXT_WIDTH);

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.
@@ -227,11 +231,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 +404,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

@@ -168,12 +168,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 +186,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 +499,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,
@@ -939,9 +940,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,7 +36,7 @@ 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 { knownGapMessage, commandPointer, commandPointerLeads, topicPointer } from "../known-gaps";
 import { selectReportTables } from "../report-tables";
 import { cliOutputWritten } from "../result";
 import type { CatalogCommandHit } from "../unknown-command";
@@ -486,6 +486,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 +497,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: {