gloomberb 0.16.4 → 0.16.6

package/src/plugins/builtin/company-attention/series.ts

@@ -0,0 +1,52 @@
+import type { AppAttentionPayload } from "../../../api-client/app-attention";
+import type { HiringPayload } from "../../../api-client/hiring";
+import type { SeriesDefinition } from "../../../series/types";
+import { fetchAttention } from "./client";
+
+const DAY_MS = 86_400_000;
+
+/** The app history window a chart asks for, in the days the server takes (7 to 730). */
+function appHistoryDays(start: Date | undefined): number {
+  if (!start) return 730;
+  return Math.min(730, Math.max(7, Math.ceil((Date.now() - start.getTime()) / DAY_MS)));
+}
+
+/**
+ * The company signals HIRE and APPS chart: observed open roles each week and
+ * the app attention score each day. Pro readings: the free preview carries no
+ * history, so they fail with the pane's own words.
+ */
+export const COMPANY_ATTENTION_SERIES: readonly SeriesDefinition[] = [
+  {
+    id: "hiring:open-roles",
+    name: "Observed open roles",
+    unit: "jobs",
+    frequency: "weekly",
+    group: "Alternative data",
+    tags: ["hiring", "hiring momentum", "roles", "requisitions", "careers"],
+    description: "Requisitions observed on public career boards each week, subsidiaries rolled up through evidenced ownership, as HIRE charts them. Needs Pro.",
+    input: "ticker",
+    load: async ({ ticker, signal }) => {
+      const data = await fetchAttention("hiring", ticker!, {}, undefined, signal) as HiringPayload;
+      if (data.preview) throw new Error("Full hiring history requires Pro.");
+      if (!data.series.length) throw new Error("History is accumulating from the first capture.");
+      return data.series.map((point) => ({ date: point.week, value: point.openCount }));
+    },
+  },
+  {
+    id: "app-attention:score",
+    name: "App attention score",
+    unit: "score",
+    frequency: "daily",
+    group: "Alternative data",
+    tags: ["apps", "app attention", "mobile", "app ranks", "ratings"],
+    description: "A 0 to 100 summary of the public chart ranks of the company's apps across countries, as APPS charts it. Needs Pro.",
+    input: "ticker",
+    load: async ({ ticker, start, signal }) => {
+      const data = await fetchAttention("apps", ticker!, { days: appHistoryDays(start) }, undefined, signal) as AppAttentionPayload;
+      if (data.access === "preview") throw new Error("Full app history requires Pro.");
+      if (!data.history.length) throw new Error("History is accumulating from the first capture.");
+      return data.history.map((point) => ({ date: point.date, value: point.attentionScore }));
+    },
+  },
+];

package/src/plugins/builtin/company-kpis/headless.ts

@@ -1,6 +1,80 @@
-import type { HeadlessPaneDefinition } from "../../../types/plugin";
+import type { DataTableColumn } from "../../../components";
+import type { HeadlessBundleSection, HeadlessPaneColumn, HeadlessPaneDefinition } from "../../../types/plugin";
+import { withoutQuietColumns } from "../shared/research-cells";
 import { resolveHeadlessIssuerListing } from "../shared/headless-market-data";
-import { companyQuery, fetchCompanyData, type CompanyMode } from "./client";
+import { companyQuery, fetchCompanyData, type CompanyDataset, type CompanyMode } from "./client";
+import { allGuidance, allObservations, companyCellText, companyColumns, companyPreviewNote, QUIET_COLUMNS, type CompanyRow } from "./model";
+import type { KpiObservation } from "../../../api-client/company-kpis";
+
+/** What the server takes as a metric; anything else is not a metric id and is not sent. */
+const METRIC_ID = /^[a-z0-9_]{1,80}$/;
+/** Filters the free preview ignores: it is fixed at the latest disclosures. */
+const PRO_FILTERS = ["basis", "from", "to", "asOf"] as const;
+/** The row field behind each pane column, where there is one; exports keep that field's value. */
+const ROW_KEYS: Record<string, string> = { scope: "dimensions", issued: "issuedDate" };
+
+/**
+ * The pane's table columns, printed as the pane prints them: fiscal labels
+ * (FY2024), compact values with their unit (12.48B USD), the scope in words,
+ * and Basis and Scope only when a row is not the reported, consolidated
+ * figure. Each row's disclosure date follows. The rows keep every field the
+ * server sent for exports.
+ */
+function reportColumns(mode: CompanyMode, history: boolean, revisions: boolean, rows: CompanyRow[], observations: KpiObservation[]): HeadlessPaneColumn[] {
+  const columns: DataTableColumn[] = [...companyColumns(mode === "guidance", false, history),
+    ...(revisions ? [{ id: "revision", label: "Revision", width: 12, align: "left" as const }] : [])];
+  return [...withoutQuietColumns(columns, rows, (row, id) => companyCellText(row, id, observations), QUIET_COLUMNS).map((column): HeadlessPaneColumn => ({
+    key: column.id === "value" && mode === "guidance" ? "rangeText" : ROW_KEYS[column.id] ?? column.id, header: column.label, align: column.align === "right" ? "right" : "left",
+    format: (_value, row) => companyCellText(row as unknown as CompanyRow, column.id, observations),
+  })), { key: "asOf", header: "As of", format: (value) => typeof value === "string" ? value.slice(0, 10) : "--" }];
+}
+
+function datasetRows(data: CompanyDataset): CompanyRow[] {
+  return "series" in data ? allObservations(data) : allGuidance(data);
+}
+
+/** The metrics a report has rows for, `revenue (Revenue)`, in the order the server lists them. */
+function metricList(rows: CompanyRow[]): string {
+  return [...new Map(rows.map((row) => [row.metricId, `${row.metricId} (${row.metric.name})`])).values()].join(", ");
+}
+
+/**
+ * The free preview is fixed, so a metric asked for is picked out of it here,
+ * never answered with another metric's rows. An id the dictionary does not
+ * know fails naming the ones this company has. A known metric the preview has
+ * no rows for may be among the values it holds back, so that case gives the
+ * preview's own counts; only a company with nothing held back has none.
+ */
+function metricFilter(requested: string, data: CompanyDataset, mode: CompanyMode): { keep: (row: CompanyRow) => boolean; empty?: string } {
+  if (!requested) return { keep: () => true };
+  const rows = datasetRows(data);
+  const whose = data.access === "preview" ? `${data.symbol}'s free preview` : data.symbol;
+  const offered = metricList(rows);
+  const has = offered ? `${whose} has ${offered}` : `${whose} has no ${mode === "kpis" ? "KPI" : "guidance"} disclosures`;
+  const known = data.dictionary.find((metric) => metric.id === requested) ?? rows.find((row) => row.metricId === requested)?.metric;
+  if (!known) throw new Error(`${requested} is not a known metric id. ${has}.`);
+  const keep = (row: CompanyRow) => row.metricId === requested;
+  if (rows.some(keep)) return { keep };
+  if (data.access === "preview" && data.lockedRows > 0) {
+    const shown = Math.max(0, data.totalRows - data.lockedRows);
+    const noun = (count: number) => `${mode === "kpis" ? "KPI value" : "guidance figure"}${count === 1 ? "" : "s"}`;
+    const all = `Gloom Pro shows all ${data.totalRows.toLocaleString("en-US")}`;
+    return { keep, empty: shown === 0 ? `The free preview shows no ${noun(0)}; ${all}.`
+      : `${known.name} is not ${shown === 1 ? "the" : "among the"} ${shown.toLocaleString("en-US")} free ${noun(shown)}; ${all}.` };
+  }
+  return { keep, empty: `${data.symbol} has no ${known.name} (${known.id}) ${mode === "kpis" ? "disclosures" : "guidance"}${offered ? `; it has ${offered}` : ""}.` };
+}
+
+/**
+ * How old a free preview's rows are: the footer dates the company's newest
+ * disclosure, which the fixed preview may not show.
+ */
+function ageNote(data: CompanyDataset, latest: CompanyRow[], mode: CompanyMode): string | null {
+  const shown = latest.map((row) => row.asOf.slice(0, 10)).sort().at(-1);
+  const newest = data.asOf?.slice(0, 10);
+  if (data.access !== "preview" || !shown || !newest || newest <= shown) return null;
+  return `The free preview's latest ${mode === "kpis" ? "KPIs are" : "guidance is"} as of ${shown}, older than ${data.symbol}'s newest disclosure (${newest}).`;
+}
 
 export function companyHeadless(mode: CompanyMode): HeadlessPaneDefinition<"bundle"> {
   return {
@@ -8,10 +82,10 @@ export function companyHeadless(mode: CompanyMode): HeadlessPaneDefinition<"bund
     freshness: { source: "Company filings and calls", status: "not-a-feed", basis: "reported data" },
     argument: { kind: "ticker", description: "Listed company ticker, including exchange-qualified global symbols.", placeholder: "ticker" },
     discovery: { aliases: [mode === "kpis" ? "KPIS" : "GUIDE"], dataRequirements: ["Gloom Cloud company disclosures"],
-      limitations: ["Pro dataset with a fixed latest preview on Free", "Coverage follows available company disclosures; missing data is not zero", "Compare matching definition, period, currency, basis and scope", "Fiscal labels without explicit calendar dates are retained without inferred dates"] },
+      limitations: ["Pro dataset with a fixed latest preview on Free.", "Coverage follows available company disclosures; missing data is not zero.", "Compare matching definition, period, currency, basis and scope.", "Fiscal labels without explicit calendar dates are retained without inferred dates."] },
     options: [
       { key: "tab", type: "enum", settingKey: "tab", defaultValue: "table", values: [{ value: "table" }, { value: "chart" }, ...(mode === "guidance" ? [{ value: "history" }] : []), { value: "evidence" }], description: "The pane section to render." },
-      { key: "metric", type: "string", settingKey: "metric", description: "Canonical metric ID, such as arr or subscribers." },
+      { key: "metric", type: "string", settingKey: "metric", description: "Canonical metric ID, such as arr or subscribers.", normalize: (value) => value.trim().toLowerCase() },
       { key: "basis", type: "enum", values: [{ value: "reported" }, { value: "adjusted" }, { value: "constant_currency" }, { value: "organic" }], description: "Accounting basis filter (Pro)." },
       { key: "from", type: "string", description: "First calendar period end, YYYY-MM-DD (Pro)." },
       { key: "to", type: "string", description: "Last calendar period end, YYYY-MM-DD (Pro)." },
@@ -19,15 +93,28 @@ export function companyHeadless(mode: CompanyMode): HeadlessPaneDefinition<"bund
     ],
     describe: (args) => `${mode === "kpis" ? "Company KPIs" : "Company guidance"} | ${args.symbols[0]}`,
     async load(args, ctx) {
-      const options = companyQuery(args.options);
+      const requested = typeof args.options.metric === "string" && args.options.metric !== "all" ? args.options.metric.trim().toLowerCase() : "";
+      const options = companyQuery({ ...args.options, metric: METRIC_ID.test(requested) ? requested : undefined });
       const symbol = args.symbols[0]!;
       const data = await fetchCompanyData(mode, symbol, options, ctx.apiClient, await resolveHeadlessIssuerListing(ctx, symbol));
-      return { complete: !data.truncated, errors: data.truncated ? [data.access === "preview" ? "Full disclosures and history require Gloom Pro" : "Response limit reached; narrow the metric or date range"] : [],
+      const { keep, empty } = metricFilter(requested, data, mode);
+      const observations = "series" in data ? allObservations(data) : [];
+      // A metric with no rows says why once, in the first section.
+      const section = (title: string, rows: CompanyRow[], { history = false, revisions = false, first = false } = {}): HeadlessBundleSection => {
+        const shown = rows.filter(keep);
+        return { title, columns: reportColumns(mode, history, revisions, shown, observations), rows: shown.map((row) => ({ ...row })), ...(empty && first ? { empty } : {}) };
+      };
+      const latest = ("series" in data ? data.series.map((series) => series.latest) : data.guidance).filter(keep);
+      const ignored = data.access === "preview" ? PRO_FILTERS.filter((key) => typeof args.options[key] === "string" && args.options[key] !== "") : [];
+      const notes = [ageNote(data, latest, mode),
+        ignored.length ? `The free preview is fixed: ${ignored.map((key) => `--${key}`).join(", ")} ${ignored.length > 1 ? "need" : "needs"} Gloom Pro.` : null].filter((note): note is string => !!note);
+      return { complete: !data.truncated, errors: data.truncated ? [data.access === "preview" ? companyPreviewNote(data, mode === "guidance") : "Response limit reached; narrow the metric or date range"] : [],
+        ...(notes.length ? { notes } : {}),
         sections: "series" in data ? [
-          { title: "Latest KPIs", rows: data.series.map((series) => ({ ...series.latest })) },
-          { title: "KPI history", rows: data.series.flatMap((series) => series.observations.map((row) => ({ ...row }))) },
-          { title: "Revisions and conflicts", rows: data.revisions.map((row) => ({ ...row })) },
-        ] : [{ title: "Current guidance", rows: data.guidance.map((row) => ({ ...row })) }, { title: "Guidance history", rows: data.history.map((row) => ({ ...row })) }],
+          section("Latest KPIs", data.series.map((series) => series.latest), { first: true }),
+          section("KPI history", data.series.flatMap((series) => series.observations)),
+          section("Revisions and conflicts", data.revisions, { revisions: true }),
+        ] : [section("Current guidance", data.guidance, { first: true }), section("Guidance history", data.history, { history: true })],
         metadata: { symbol: data.symbol, asOf: data.asOf, access: data.access, coverage: data.coverage, dictionary: data.dictionary,
           lockedRows: data.lockedRows, totalRows: data.totalRows, methodology: data.methodology } };
     },

package/src/plugins/builtin/company-kpis/model.ts

@@ -3,6 +3,7 @@ import type { DataTableColumn } from "../../../components";
 import { scalarPoint, staticSeries } from "../../../components/chart/static/series";
 import type { CompositeChartXAxis } from "../../../components/chart/composite/types";
 import { formatCompact, formatNumber } from "../../../utils/format";
+import { freePreviewNote } from "../shared/free-preview";
 
 export type CompanyRow = KpiObservation | KpiGuidance;
 export const isGuidance = (row: CompanyRow): row is KpiGuidance => "issuedDate" in row;
@@ -29,7 +30,7 @@ export const rangeText = (row: KpiGuidance, withUnit = true) => row.status === "
   : row.low !== null ? `${row.hedge === "greater_than" ? ">" : "≥"} ${valueText(row, row.low, withUnit)}`
   : row.high !== null ? `${row.hedge === "less_than" ? "<" : "≤"} ${valueText(row, row.high, withUnit)}` : row.rangeText;
 /** The unit a value cell carries after its number; percent, bp and x are already in the number. */
-export function unitSuffix(row: Pick<CompanyRow, "unit" | "currency" | "dimensions">): string {
+function unitSuffix(row: Pick<CompanyRow, "unit" | "currency" | "dimensions">): string {
   if (row.unit === "currency") return row.currency ? ` ${row.currency}` : "";
   if (row.unit === "currency_per_share") return ` ${row.currency ?? ""}/sh`.replace(" /", " ");
   if (row.unit === "currency_per_unit" || row.unit === "volume") return ` ${unitLabel(row)}`;
@@ -68,7 +69,7 @@ export function observationChange(row: KpiObservation, observations: KpiObservat
   return { value: (row.value - prior.value) / Math.abs(prior.value) * 100, unit: "%" };
 }
 export const changeText = (change: { value: number | null; unit: string }) => change.value === null ? "--" : `${change.value > 0 ? "+" : ""}${formatNumber(change.value, 2)}${change.unit}`;
-export const fiscalLabel = (row: CompanyRow) => row.period.fiscalYear === null ? row.period.label
+export const fiscalLabel = (row: Pick<CompanyRow, "period">) => row.period.fiscalYear === null ? row.period.label
   : row.period.kind === "year" ? `FY${row.period.fiscalYear}`
   : row.period.fiscalQuarter !== null ? `Q${row.period.fiscalQuarter} FY${row.period.fiscalYear}${row.period.kind === "ytd" ? " YTD" : ""}` : row.period.label;
 export const periodOrder = (row: CompanyRow) => row.period.fiscalYear !== null
@@ -104,6 +105,19 @@ export function guidanceSeries(rows: KpiGuidance[], selected: KpiGuidance | unde
   if (actual && series.length) series.push(staticSeries(timeline.map((row) => scalarPoint(new Date(row.issuedDate), actual.value)), { id: "actual", label: "Later actual", color: colors.actual, calendarSpaced: true }));
   return series;
 }
+/** Columns that say nothing while every row is the company's consolidated, as-reported figure. */
+export const QUIET_COLUMNS = { basis: ["Reported"], scope: ["Consolidated"] };
+/** The text of a table cell as the pane draws it; the report prints the same words. */
+export function companyCellText(row: CompanyRow, column: string, observations: KpiObservation[]): string {
+  const guide = isGuidance(row) ? row : null;
+  if (column === "change") return guide ? directionLabel(guide.direction) : changeText(observationChange(row as KpiObservation, observations));
+  return column === "metric" ? row.metric.name : column === "period" ? fiscalLabel(row) : column === "value" ? `${guide ? rangeText(guide) : observationValue(row as KpiObservation)}${guide?.status === "withdrawn" || guide?.hedge === "qualitative" ? "" : unitSuffix(row)}`
+    : column === "unit" ? unitLabel(row)
+    : column === "basis" ? basisLabel(row.basis) : column === "scope" ? dimensionLabel(row.dimensions) || "Consolidated"
+    : column === "issued" ? guide?.issuedDate ?? "--" : column === "actual" ? guide?.actual ? `${valueText(row, guide.actual.value)}${unitSuffix(row)}` : "--"
+    : column === "outcome" ? guide ? outcomeLabel(guide) : "--" : column === "published" ? row.evidence[0]!.publishedAt.slice(0, 10)
+    : column === "confidence" ? `${Math.round(row.confidence * 100)}%` : column === "revision" ? `${row.revision} ${row.current ? "current" : "superseded"}` : row.evidence[0]!.quote;
+}
 export function companyColumns(guidance: boolean, evidence: boolean, history: boolean, trend = false): DataTableColumn[] {
   const columns: DataTableColumn[] = [
     { id: "metric", label: "Metric", width: 27, flexGrow: 1, align: "left" },
@@ -122,3 +136,11 @@ export function companyColumns(guidance: boolean, evidence: boolean, history: bo
     : history ? ["metric", "period", "actual", "outcome", "value", "issued", "change", "basis", "scope"] : null;
   return order ? columns.sort((a, b) => order.indexOf(a.id) - order.indexOf(b.id)) : columns;
 }
+
+/** The lock line of a free preview, in the same words in the pane and `fn KPIS` / `fn GUIDE`. */
+export function companyPreviewNote(data: Pick<KpisPayload, "lockedRows" | "totalRows" | "coverage">, guidance: boolean): string {
+  const count = (value: number) => value.toLocaleString("en-US");
+  const rows = `${count(data.totalRows)} ${guidance ? "guidance figures" : "KPI values"}`;
+  return freePreviewNote({ shows: data.lockedRows > 0 ? `${count(Math.max(0, data.totalRows - data.lockedRows))} of ${rows}` : rows,
+    adds: data.lockedRows > 0 ? `the other ${count(data.lockedRows)}` : null, historyFrom: data.coverage.firstPeriod });
+}

package/src/plugins/builtin/company-kpis/pane.tsx

@@ -13,21 +13,22 @@ import type { PaneProps } from "../../../types/plugin";
 import { Box, Text, useRendererHost, useUiCapabilities, type ScrollBoxRenderable } from "../../../ui";
 import { SignInWall } from "../cloud/auth-actions";
 import { CLOUD_PLAN_KEY, useCloudUpgradeAction } from "../shared/cloud-upgrade";
+import { useOpenDescription } from "../shared/open-description";
 import { Blurred, LockedOverlay, UpgradeLabel } from "../shared/locked-rows";
 import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
 import { cachedCompanyData, loadCompanyData, KPI_UNAVAILABLE, validateCompanyData, type CompanyDataset, type CompanyMode } from "./client";
 import { useCompanyEvidence } from "./screenshot-evidence";
-import { allGuidance, allObservations, basisLabel, changeText, changeTone, companyColumns, dimensionLabel, directionLabel, directionTone, guideGroupKey, guidanceSeries, fiscalLabel,
-  isGuidance, exactObservation, observationValue, observationChange, observationChart, periodOrder, outcomeLabel, rangeText, seriesLabel, unitLabel, unitSuffix, valueText, type CompanyRow } from "./model";
+import { allGuidance, allObservations, basisLabel, changeText, changeTone, companyCellText, companyColumns, dimensionLabel, directionLabel, directionTone, guideGroupKey, guidanceSeries, fiscalLabel,
+  isGuidance, exactObservation, observationValue, observationChange, observationChart, periodOrder, outcomeLabel, QUIET_COLUMNS, rangeText, seriesLabel, unitLabel, valueText, companyPreviewNote,
+  type CompanyRow } from "./model";
 import { PriceSparkline } from "../../../components/price-sparkline/view";
 import type { PricePoint } from "../../../types/financials";
 import { toneColor, withoutQuietColumns } from "../shared/research-cells";
 
-/** Columns that say nothing while every row is the company's consolidated, as-reported figure. */
-const QUIET_COLUMNS = { basis: ["Reported"], scope: ["Consolidated"] };
-
-type Item = { id: string; row: CompanyRow } | { id: string; row: null };
+/** A locked placeholder, or with `note` the line above them saying what free shows and what Pro adds. */
+type Item = { id: string; row: CompanyRow } | { id: string; row: null; note?: string };
 const getId = (item: Item) => item.id;
+const isNote = (item: Item) => "note" in item && !!item.note;
 function DisclosureEvidence({ row, sourceId, onSource, width }: { row: CompanyRow; sourceId: string | null; onSource: (id: string) => void; width: number }) {
   const colors = useThemeColors();
   const evidence = row.evidence.find((entry) => entry.id === sourceId) ?? row.evidence[0]!;
@@ -77,6 +78,7 @@ function CompanyView({ symbol, exchange, name, mode, width, height, focused }: P
   const host = useRendererHost();
   const desktop = !!useUiCapabilities().nativePaneChrome;
   const { createPaneFromTemplate } = usePluginAppActions();
+  const openDescription = useOpenDescription();
   const session = useResearchCloudSession();
   const access = usePlanAccess();
   const accessKey = `${session.requestKey}:${access.hasProAccess ? "full" : "preview"}`;
@@ -132,7 +134,9 @@ function CompanyView({ symbol, exchange, name, mode, width, height, focused }: P
   const activeRow = openRow ?? selected;
   const preview = data?.access === "preview" && data.lockedRows > 0;
   const lockedCount = preview ? Math.min(3, data.lockedRows) : 0;
-  const items = useMemo<Item[]>(() => [...rows.map((row) => ({ id: row.id, row })), ...Array.from({ length: lockedCount }, (_, index) => ({ id: `locked:${index}`, row: null }))], [rows, lockedCount]);
+  const previewNote = preview ? companyPreviewNote(data, mode === "guidance") : null;
+  const items = useMemo<Item[]>(() => [...rows.map((row) => ({ id: row.id, row })), ...(previewNote ? [{ id: "note:preview", row: null, note: previewNote }] : []),
+    ...Array.from({ length: lockedCount }, (_, index) => ({ id: `locked:${index}`, row: null }))], [rows, lockedCount, previewNote]);
   // One trend per series beside its latest value, once a series has three comparable points.
   const trends = useMemo(() => {
     const map = new Map<string, PricePoint[]>();
@@ -165,10 +169,10 @@ function CompanyView({ symbol, exchange, name, mode, width, height, focused }: P
     ...(preview ? [{ id: "upgrade", key: CLOUD_PLAN_KEY, label: "upgrade", title: "Upgrade to Pro", onPress: openUpgrade }] : []),
   ];
   usePaneMenuItems("company-disclosures:research", () => symbol ? [
-    { id: "description", label: "Description (DES)", onSelect: () => createPaneFromTemplate("new-ticker-detail-pane", { symbol }) },
+    { id: "description", label: "Description (DES)", onSelect: () => openDescription(symbol) },
     { id: "financials", label: "Financial Analysis (FA)", onSelect: () => createPaneFromTemplate("financial-analysis-pane", { symbol }) },
     { id: "price-chart", label: "Price Chart (G)", onSelect: () => createPaneFromTemplate("chart-composer-pane", { arg: symbol }) },
-  ] : null, [symbol, createPaneFromTemplate]);
+  ] : null, [symbol, createPaneFromTemplate, openDescription]);
   usePaneStatusFooter({ registrationId: "company-kpis", loading: resource.loading, error: data ? resource.error : null, stale: resource.data?.stale,
     info: data?.asOf ? [{ id: "as-of", parts: [{ text: `as of ${data.asOf.slice(0, 10)}`, tone: "muted" as const }] }] : [], hints });
   usePaneNoticeFooter({ registrationId: "company-kpis:notices", focused, notices: [resource.data?.refreshError,
@@ -183,6 +187,7 @@ function CompanyView({ symbol, exchange, name, mode, width, height, focused }: P
   const renderCell = (item: Item, column: (typeof columns)[number]): DataTableCell => {
     const row = item.row;
     if (!row) {
+      if (isNote(item)) return { text: "" };
       if (!desktop && column.id === "metric" && item.id === "locked:0") return { text: "Unlock with Pro", content: <UpgradeLabel text="Unlock with Pro" onPress={openUpgrade} />, onMouseDown: openUpgrade };
       return desktop ? { text: "", content: <Blurred><Text fg={colors.textDim}>{column.id === "metric" ? "Additional disclosure" : "Hidden"}</Text></Blurred> } : { text: "░░░░░", color: colors.textDim };
     }
@@ -199,12 +204,7 @@ function CompanyView({ symbol, exchange, name, mode, width, height, focused }: P
       const change = observationChange(row as KpiObservation, observations);
       return { text: changeText(change), value: change.value, color: toneColor(changeTone(row as KpiObservation, change.value), colors) };
     }
-    const text = column.id === "metric" ? row.metric.name : column.id === "period" ? fiscalLabel(row) : column.id === "value" ? `${guide ? rangeText(guide) : observationValue(row as KpiObservation)}${guide?.status === "withdrawn" || guide?.hedge === "qualitative" ? "" : unitSuffix(row)}`
-      : column.id === "unit" ? unitLabel(row)
-      : column.id === "basis" ? basisLabel(row.basis) : column.id === "scope" ? dimensionLabel(row.dimensions) || "Consolidated"
-      : column.id === "issued" ? guide?.issuedDate ?? "--" : column.id === "actual" ? guide?.actual ? `${valueText(row, guide.actual.value)}${unitSuffix(row)}` : "--"
-      : column.id === "outcome" ? guide ? outcomeLabel(guide) : "--" : column.id === "published" ? row.evidence[0]!.publishedAt.slice(0, 10)
-      : column.id === "confidence" ? `${Math.round(row.confidence * 100)}%` : column.id === "revision" ? `${row.revision} ${row.current ? "current" : "superseded"}` : row.evidence[0]!.quote;
+    const text = companyCellText(row, column.id, observations);
     return { text, ...(column.id === "value" && !guide ? { value: exactObservation(row as KpiObservation) ? (row as KpiObservation).value : observationValue(row as KpiObservation) } : column.id === "actual" ? { value: guide?.actual?.value } : {}),
       color: column.id === "metric" ? colors.textBright : column.id === "value" || column.id === "actual" ? colors.textBright
         : column.id === "outcome" && guide?.actual ? guide.actual.favorable === "beat" ? colors.positive : guide.actual.favorable === "miss" ? colors.negative : colors.text
@@ -217,7 +217,8 @@ function CompanyView({ symbol, exchange, name, mode, width, height, focused }: P
       empty={!data && resource.error === KPI_UNAVAILABLE} emptyTitle={KPI_UNAVAILABLE} subject="company disclosures">
       {data ? <DataTableStackView<Item> focused={focused} rootWidth={width} rootHeight={bodyHeight} columns={columns} items={items} getItemKey={getId}
         selection={{ kind: "id", selectedId: selected?.id ?? null, getId, onChange: setSelected }}
-        onActivate={(item) => item.row ? setOpen(item.row.id) : openUpgrade()} renderCell={renderCell} freezeFirstColumn selectedTextOverridesCellColor showHorizontalScrollbar
+        onActivate={(item) => item.row ? setOpen(item.row.id) : isNote(item) ? undefined : openUpgrade()} renderCell={renderCell}
+        isNavigable={(item) => !isNote(item)} renderSectionHeader={(item) => "note" in item && item.note ? { text: item.note } : null} freezeFirstColumn selectedTextOverridesCellColor showHorizontalScrollbar
         detailOpen={!!openRow} onBack={() => setOpen(null)} detailTitle={openRow ? `${openRow.metric.name} · ${fiscalLabel(openRow)}` : undefined}
         detailScrollRef={detailScrollRef} detailContent={openRow ? <DetailScrollBody ref={detailScrollRef} resetScrollKey={openRow.id}><DisclosureEvidence row={openRow} sourceId={sourceId} onSource={setSource} width={width} /></DetailScrollBody> : null}
         sortColumnId={sort.column} sortDirection={sort.direction} onHeaderClick={(column) => setSort((previous) => ({ column, direction: previous.column === column && previous.direction === "desc" ? "asc" : "desc" }))}

package/src/plugins/builtin/composite-plugins.ts

@@ -32,6 +32,7 @@ import { cotModule } from "./cot";
 import { doeModule } from "./doe";
 import { gpuModule } from "./gpu";
 import { fxMatrixModule } from "./fx-matrix";
+import { docsModule } from "./docs";
 import { helpModule } from "./help";
 import { positionSizerModule } from "./kelly-sizer";
 import { layoutManagerModule } from "./layout-manager";
@@ -57,6 +58,7 @@ import { socialMentionsModule } from "./social-mentions";
 import { timeSalesModule } from "./time-sales";
 import { estimateRevisionsModule } from "./estimate-revisions";
 import { chartComposerModule } from "./chart-composer";
+import { userSeriesModule } from "./chart-composer/user-series";
 import { congressResearchModule } from "./congress-trades";
 import { dividendYieldModule } from "./dividend-yield";
 import { executivesModule } from "./executives";
@@ -104,7 +106,7 @@ import {
 
 export const applicationPlugin = composeBuiltinPlugin({
   ...applicationPluginMeta,
-  modules: [layoutManagerModule, pluginMarketplaceModule, helpModule, changelogModule, connectionsModule],
+  modules: [layoutManagerModule, pluginMarketplaceModule, helpModule, changelogModule, connectionsModule, docsModule],
 });
 
 export const portfolioPlugin = composeBuiltinPlugin({
@@ -121,18 +123,22 @@ const tickerResearchModule = (module: PluginModule) => ({ module, stateId: "tick
 export const tickerCorePlugin = composeBuiltinPlugin({
   ...tickerCorePluginMeta,
   modules: [
-    tickerDetailModule,
-    chartComposerModule,
-    researchModule,
-    estimateRevisionsModule,
-    companyKpisModule,
-    revenueBreakdownModule,
-    dividendYieldModule,
-    reverseDcfModule,
-    peBandModule,
-    executivesModule,
-    timeSalesModule,
-  ].map(rendererOnly),
+    ...[
+      tickerDetailModule,
+      chartComposerModule,
+      researchModule,
+      estimateRevisionsModule,
+      companyKpisModule,
+      revenueBreakdownModule,
+      dividendYieldModule,
+      reverseDcfModule,
+      peBandModule,
+      executivesModule,
+      timeSalesModule,
+    ].map(rendererOnly),
+    // Reads the profile's series folder, so it runs where the disk is: the desktop backend too.
+    userSeriesModule,
+  ],
 });
 
 export const optionsVolatilityPlugin = composeBuiltinPlugin({

package/src/plugins/builtin/connections/index.ts

@@ -33,6 +33,7 @@ export const connectionsModule: PluginModule = {
   panes: [{
     id: "connections",
     name: "Connections",
+    personalData: "account",
     icon: "C",
     component: ConnectionsPane,
     defaultPosition: "right",

package/src/plugins/builtin/cot/headless.ts

@@ -32,7 +32,7 @@ export const cotHeadless: HeadlessPaneDefinition<"bundle"> = {
   options: [{ key: "report", type: "enum", values: [{ value: "legacy" }, { value: "disaggregated" }], defaultValue: "legacy", description: "CFTC report family." },
     { key: "traderClass", type: "enum", values: ["noncommercial", "commercial", "producer", "swap", "managed-money", "other-reportable", "nonreportable"].map((value) => ({ value })), description: "Trader class for the extremes board; defaults by report family." },
     { key: "scope", type: "enum", values: COT_SCOPES.map(({ value }) => ({ value })), defaultValue: "major", description: "Markets on the extremes board, as in the pane." }],
-  discovery: { aliases: ["COT", "CFTC"], dataRequirements: ["Gloom Cloud CFTC history"], limitations: ["Futures-only positions aggregate all maturities", "Legacy and disaggregated classes differ", "Observation date is not publication date", "Some markets have short or suppressed histories"] },
+  discovery: { aliases: ["COT", "CFTC"], dataRequirements: ["Gloom Cloud CFTC history"], limitations: ["Futures-only positions aggregate all maturities.", "Legacy and disaggregated classes differ.", "Observation date is not publication date.", "Some markets have short or suppressed histories."] },
   describe: "CFTC positioning",
   async load(args, ctx) {
     const family = args.options.report === "disaggregated" ? "disaggregated" : "legacy";

package/src/plugins/builtin/cot/index.tsx

@@ -3,14 +3,16 @@ import { cotBoardCache } from "./client";
 import { cotHeadless } from "./headless";
 import { COT_ROOT_OPTIONS, cotContractCode, cotContractCodeForTicker, cotRoot, cotUnknownMarketMessage } from "./model";
 import { CotPane } from "./pane";
+import { COT_SERIES } from "./series";
 
 export const cotModule: PluginModule = {
+  series: COT_SERIES,
   panes: [{ id: "cot", name: "CFTC Positioning", icon: "P", component: CotPane,
     defaultPosition: "right", defaultMode: "floating", defaultFloatingSize: { width: 106, height: 30 },
     tableExport: true, headless: cotHeadless }],
   paneTemplates: [{ id: "cot-cot", paneId: "cot", label: "CFTC Positioning",
     description: "Weekly futures positioning, changes, historical percentiles and cross-market extremes.",
-    keywords: ["cot", "cftc", "positioning", "commitments", "managed money", "net spec"],
+    keywords: ["cot", "cftc", "positioning", "commitments", "managed money", "net spec", "crude oil", "natural gas"],
     shortcut: { prefix: "COT", aliases: ["CFTC"], argKind: "text" as const, argPlaceholder: "code or root", argOptional: true,
       argOptions: () => COT_ROOT_OPTIONS }, headless: cotHeadless,
     createInstance: (context, options) => {

package/src/plugins/builtin/cot/model.ts

@@ -5,6 +5,7 @@ import type { PricePoint } from "../../../types/financials";
 import { formatPriceObservation } from "../../../market-data/market/format";
 import { cleanFloat32Price } from "../../../cli/history-rows";
 import { cryptoPairCoin, isFuturesSymbol } from "../shared/crypto-pair";
+import { FUTURES_CONTRACTS, futuresBoardContract, futuresBoardContractForTicker, type FuturesContract } from "../../../market-data/futures-board";
 
 export const COT_CLASSES: Record<CotFamily, Array<{ value: CotClass; label: string }>> = {
   legacy: [{ value: "noncommercial", label: "Noncommercial" }, { value: "commercial", label: "Commercial" }, { value: "nonreportable", label: "Nonreportable" }],
@@ -29,7 +30,7 @@ const ROOTS: Record<string, { code: string; exchange: string; priceSymbol: strin
   SOL: { code: "177741", exchange: "CME", priceSymbol: null, name: "Solana", crypto: true },
   XRP: { code: "176740", exchange: "CME", priceSymbol: null, name: "XRP", crypto: true },
 };
-/** The roots `cotContractCode` accepts, labeled "ZQ 30-Day Fed Funds". */
+/** The verified root aliases, labeled "ZQ 30-Day Fed Funds"; `cotContractCode` also takes every FUT board root the CFTC reports. */
 export const COT_ROOT_OPTIONS = Object.entries(ROOTS).map(([root, row]) => ({ value: root, label: root === row.name ? root : `${root} ${row.name}` }));
 /** The crypto roots named for a coin, which a coin pair (BTC-USD) can stand for. The micros have no pair. */
 const COIN_PAIR_ROOTS: ReadonlySet<string> = new Set(["BTC", "ETH", "SOL", "XRP"]);
@@ -37,9 +38,12 @@ const COIN_PAIR_ROOTS: ReadonlySet<string> = new Set(["BTC", "ETH", "SOL", "XRP"
  * Front-month price overlays for major markets without a root alias, each
  * checked to return five years of daily history (2026-09-24). Keyed by CFTC
  * code, never added to ROOTS: an alias would also claim the equity ticker under
- * the cursor (ZM, ZS, PL). No cash index stands in, so the dollar index has none.
- * Bitcoin and ether are in ROOTS, where `cotContractCodeForTicker` keeps the
- * same guard for their aliases.
+ * the cursor (ZM, ZS, PL). A FUT board root typed as an argument finds its
+ * market here through its price symbol (NG is NG=F, so 023651). No cash index
+ * stands in, so the dollar index has none. Orange juice and lumber were added
+ * on 2026-10-11 so their board roots open a market; lumber's contract (LBR)
+ * started in August 2022, so its price begins there. Bitcoin and ether are in
+ * ROOTS, where `cotContractCodeForTicker` keeps the same guard for their aliases.
  */
 const PRICE_OVERLAYS: Record<string, { exchange: string; priceSymbol: string }> = {
   "209742": { exchange: "CME", priceSymbol: "NQ=F" }, "239742": { exchange: "CME", priceSymbol: "RTY=F" },
@@ -60,9 +64,16 @@ const PRICE_OVERLAYS: Record<string, { exchange: string; priceSymbol: string }>
   "007601": { exchange: "CBT", priceSymbol: "ZL=F" }, "026603": { exchange: "CBT", priceSymbol: "ZM=F" },
   "083731": { exchange: "NYB", priceSymbol: "KC=F" }, "080732": { exchange: "NYB", priceSymbol: "SB=F" },
   "033661": { exchange: "NYB", priceSymbol: "CT=F" }, "073732": { exchange: "NYB", priceSymbol: "CC=F" },
+  "040701": { exchange: "NYB", priceSymbol: "OJ=F" }, "058644": { exchange: "CME", priceSymbol: "LBR=F" },
   "057642": { exchange: "CME", priceSymbol: "LE=F" }, "054642": { exchange: "CME", priceSymbol: "HE=F" },
   "061641": { exchange: "CME", priceSymbol: "GF=F" },
 };
+/** The CFTC market a FUT board root reports under, by its price symbol; null for one the CFTC does not report (TTF). */
+function boardMarketCode(contract: FuturesContract): string | null {
+  return Object.values(ROOTS).find((row) => row.priceSymbol === contract.symbol)?.code
+    ?? Object.entries(PRICE_OVERLAYS).find(([, row]) => row.priceSymbol === contract.symbol)?.[0]
+    ?? null;
+}
 /**
  * The markets most readers mean by "positioning", verified against the live
  * CFTC boards on 2026-09-22. A code missing from a report family simply does
@@ -90,14 +101,26 @@ export const COT_SCOPES = [{ value: "major", label: "Major markets" }, { value:
 export type CotScope = typeof COT_SCOPES[number]["value"];
 export function cotScope(value: unknown): CotScope { return value === "all" ? "all" : "major"; }
 
-/** A CFTC code or root typed as an argument or stored in a pane: every alias, crypto included. */
+const rootAlias = (input: string) => ROOTS[input === "VIX" ? "VX" : input]?.code ?? null;
+const marketCode = (input: string) => /^[0-9A-Z]{5}[0-9A-Z+]$/.test(input) ? input : null;
+/**
+ * A CFTC code or root typed as an argument or stored in a pane: every alias,
+ * crypto included, and every FUT board root the CFTC reports. A typed root is
+ * always the future, so ZM here is soybean meal, never Zoom.
+ */
 export function cotContractCode(value: unknown): string | null {
   if (typeof value !== "string") return null;
   const input = value.trim().toUpperCase().replace(/=F$/, "");
-  return ROOTS[input === "VIX" ? "VX" : input]?.code ?? (/^[0-9A-Z]{5}[0-9A-Z+]$/.test(input) ? input : null);
+  const board = futuresBoardContract(value);
+  return rootAlias(input) ?? (board ? boardMarketCode(board) : null) ?? marketCode(input);
 }
-/** What a market that is neither a root nor a CFTC code is told, with ones that work. */
+/**
+ * What a market `cotContractCode` does not know is told: a FUT board root the
+ * CFTC does not report says so; anything else gets roots and a code that work.
+ */
 export function cotUnknownMarketMessage(value: unknown): string {
+  const board = futuresBoardContract(value);
+  if (board) return `${board.code} (${board.name}) is not reported in the CFTC COT.`;
   const roots = ["ES", "CL", "GC", "ZN"].filter((root) => ROOTS[root]);
   return `Unknown market "${String(value)}". Try ${roots.join(", ")} or a CFTC market code such as ${ROOTS.GC!.code}.`;
 }
@@ -106,18 +129,24 @@ export function cotUnknownMarketMessage(value: unknown): string {
  * argument. The crypto aliases are also US ticker symbols (Grayscale's mini
  * trusts are BTC and ETH, MetLife is MET), so a bare one is the equity's and
  * never claims the market: only a futures symbol (BTC=F) or a coin pair
- * (BTC-USD) does.
+ * (BTC-USD) does. A FUT board root claims it the same way: as its futures
+ * symbol (NG=F) or a code no security uses (ZW), never a bare code a security
+ * keeps (ZM is Zoom).
  */
 export function cotContractCodeForTicker(ticker: unknown): string | null {
   if (typeof ticker !== "string") return null;
   const coin = cryptoPairCoin(ticker);
   if (coin) return COIN_PAIR_ROOTS.has(coin) ? ROOTS[coin]!.code : null;
   const input = ticker.trim().toUpperCase().replace(/=F$/, "");
-  return ROOTS[input]?.crypto && !isFuturesSymbol(ticker) ? null : cotContractCode(ticker);
+  if (ROOTS[input]?.crypto && !isFuturesSymbol(ticker)) return null;
+  const board = futuresBoardContractForTicker(ticker);
+  return rootAlias(input) ?? (board ? boardMarketCode(board) : null) ?? marketCode(input);
 }
-/** The verified futures root a CFTC code belongs to, for titles readers recognize. */
+/** The futures root a CFTC code belongs to, for titles readers recognize: a verified alias, else its FUT board root. */
 export function cotRoot(code: string): string | null {
-  return Object.entries(ROOTS).find(([, row]) => row.code === code)?.[0] ?? null;
+  return Object.entries(ROOTS).find(([, row]) => row.code === code)?.[0]
+    ?? FUTURES_CONTRACTS.find((contract) => boardMarketCode(contract) === code)?.code
+    ?? null;
 }
 export function cotPriceMapping(code: string) { return Object.values(ROOTS).find((row) => row.code === code) ?? PRICE_OVERLAYS[code] ?? null; }
 export function cotClass(family: CotFamily, value: unknown): CotClass {

package/src/plugins/builtin/cot/series.ts

@@ -0,0 +1,27 @@
+import type { SeriesDefinition } from "../../../series/types";
+import { fetchCotContract } from "./client";
+import { COT_ROOT_OPTIONS, cotContractCode, cotNetPoints } from "./model";
+
+/**
+ * Speculative (noncommercial) net positioning for each market the COT pane
+ * names by root, from the legacy report every market is in. The pane's other
+ * trader classes and markets stay in the pane.
+ */
+export const COT_SERIES: readonly SeriesDefinition[] = COT_ROOT_OPTIONS.flatMap((option): SeriesDefinition[] => {
+  const code = cotContractCode(option.value);
+  if (!code) return [];
+  const market = option.label.startsWith(`${option.value} `) ? option.label.slice(option.value.length + 1) : option.label;
+  return [{
+    id: `cot:${option.value.toLowerCase()}-noncommercial-net`,
+    name: `${market}: noncommercial net position`,
+    unit: "contracts",
+    frequency: "weekly",
+    group: "Positioning",
+    tags: ["COT", "commitments of traders", "speculators", "net spec", option.value],
+    publisher: "CFTC",
+    load: async () => {
+      const payload = await fetchCotContract(code, "legacy");
+      return { points: cotNetPoints(payload.history, "noncommercial").map((point) => ({ date: point.date, value: point.value })) };
+    },
+  }];
+});

package/src/plugins/builtin/cpi/headless.ts

@@ -42,9 +42,9 @@ export const cpiHeadless: HeadlessPaneDefinition<"bundle"> = {
   argument: { kind: "free-text", optional: true, placeholder: "component", description: "A component such as shelter, core, gasoline or supercore; omit for the table." },
   options: [],
   discovery: { aliases: ["CPI", "ECAN"], dataRequirements: ["Gloom Cloud US consumer price history"],
-    limitations: ["Monthly data, published by BLS at 08:30 ET on its release schedule",
-      "Weights and contributions are BLS's for the month; services ex shelter is computed from two BLS series",
-      "No October 2025 index was published, so changes that need it are empty"] },
+    limitations: ["Monthly data, published by BLS at 08:30 ET on its release schedule.",
+      "Weights and contributions are BLS's for the month; services ex shelter is computed from two BLS series.",
+      "No October 2025 index was published, so changes that need it are empty."] },
   describe: "US consumer prices by component",
   async load(args) {
     const data = await fetchCpiBoard();