@gloom-sh/terminal 0.18.5 → 0.19.1

package/src/plugins/builtin/credit-conditions/series.ts

@@ -1,6 +1,6 @@
 import { fredSeriesUrl } from "../../../sources/gloomberb-cloud/fred-series";
 import type { SeriesDefinition } from "../../../series/types";
-import { ICE_CREDIT_SERIES } from "../../../time-series/ice-credit";
+import { ICE_CREDIT_SERIES, ICE_HISTORY_LIMIT_NOTICE } from "../../../time-series/ice-credit";
 
 /** Corporate bond option-adjusted spreads by rating and region, and the effective yields of the US indexes. */
 export const CREDIT_SPREAD_SERIES: readonly SeriesDefinition[] = ICE_CREDIT_SERIES.map((series) => ({
@@ -11,6 +11,8 @@ export const CREDIT_SPREAD_SERIES: readonly SeriesDefinition[] = ICE_CREDIT_SERI
   group: "Credit",
   tags: [series.measure, ...series.tags, "corporate bonds"],
   publisher: "FRED",
+  // A fixed note on every ICE series. G and CRD read the same sentence from each series' FRED notes instead, so there it lapses if FRED lifts the limit.
+  limitation: ICE_HISTORY_LIMIT_NOTICE,
   url: fredSeriesUrl(series.seriesId),
   expression: `FRED:${series.seriesId}`,
 }));

package/src/plugins/builtin/credit-documents/detail.tsx

@@ -6,7 +6,7 @@ import { useThemeColors } from "../../../theme/theme-context";
 import { Box, Text, TextAttributes, useRendererHost, useUiCapabilities, type ScrollBoxRenderable } from "../../../ui";
 import { quoteBlockStyle } from "../../../components/ui/quote";
 import { fetchCreditInstrument } from "./client";
-import { comparatorSymbol, covenantNumber, covenantTerms, creditPercent, factColumns, factValue, fieldLabel, hasAmendments, headroomTone, NO_VALUE, sentence, structuredFields } from "./model";
+import { comparatorSymbol, covenantNumber, covenantReason, covenantTerms, creditPercent, factColumns, factValue, fieldLabel, hasAmendments, headroomTone, NO_VALUE, sentence, structuredFields } from "./model";
 
 const LABEL_WIDTH = 16;
 const MATCH = { exact: "Exact", whitespace: "Whitespace normalized", nfkc_whitespace: "Unicode and whitespace normalized" } as Record<string, string>;
@@ -83,7 +83,7 @@ export function CreditInstrumentDetail({ symbol, instrument, width, height, focu
   const columns = useMemo(() => factColumns(view, width), [view, width]);
   const query = <QueryBar width={width} view={{ value: view, options: [{ value: "terms", label: "Current terms" }, { value: "history", label: "Amendment history" }], onChange: (value) => { setView(value); setOpen(null); } }} />;
   // Why headroom is missing stays beside the figures it explains.
-  const reason = covenant?.reason && covenant.status !== "compliant" && covenant.status !== "breach" ? covenant.reason : null;
+  const reason = covenant ? covenantReason(covenant, data.facts) : null;
   const header = covenant ? <Box flexDirection="column">
     <ChartTableHeader width={width} height={height - (reason ? 2 : 0)} tableRows={rows.length} tableColumns={columns} query={query} figures={covenantFigures(covenant, data.facts.find((fact) => fact.id === covenant.id))} />
     {reason ? <Box paddingX={1} width={width}><Notice tone="muted">{reason}</Notice></Box> : null}

package/src/plugins/builtin/credit-documents/export.ts

@@ -0,0 +1,173 @@
+import type { CreditDocumentsPayload, CreditFact, CreditInstrument, CreditObligor, CreditScreenPayload } from "../../../api-client/credit-documents";
+import type { HeadlessBundleSection, HeadlessPaneColumn, HeadlessPaneRow } from "../../../types/plugin";
+import { capitalCell, capitalColumns, comparatorSymbol, covenantFact, covenantNumber, creditAmount, creditCurrencies, creditMaturityRows, creditPercent, factValue, fieldLabel,
+  instrumentOutstanding, isClosed, maturityShares, NO_VALUE, outstandingText, screenSignal, sentence } from "./model";
+
+/** A column the text report leaves out: the exports keep it, for ids and figures a spreadsheet reads whole. */
+type ExportColumn = HeadlessPaneColumn & { exportOnly?: boolean };
+type Section = Extract<HeadlessBundleSection, { rows: HeadlessPaneRow[] }>;
+
+const blank = (text: string) => text === NO_VALUE ? null : text;
+const name = (obligor: CreditObligor | null | undefined) => obligor?.name ?? null;
+const number = (value: unknown) => typeof value === "number" ? value : null;
+const wide = (key: string, header: string, extra: Partial<HeadlessPaneColumn> = {}): ExportColumn => ({ key, header, shrink: true, minWidth: 16, ...extra });
+const OBLIGOR: ExportColumn = { key: "obligor", header: "Obligor", minWidth: 16 };
+const INSTRUMENT_ID: ExportColumn = { key: "instrumentId", header: "Instrument ID", stackPriority: 9 };
+
+/**
+ * A table of flat records: the exports keep every column; the text report
+ * prints the pane's, and leaves out the obligor when the filing names none.
+ */
+function table(title: string, columns: readonly ExportColumn[], rows: HeadlessPaneRow[], { textKeys, empty }: { textKeys?: readonly string[]; empty?: string } = {}): Section {
+  const named = rows.some((row) => row.obligor != null);
+  const plain = (column: ExportColumn): HeadlessPaneColumn => { const { exportOnly: _, ...rest } = column; return rest; };
+  return { title, columns: columns.map(plain), rows,
+    textColumns: columns.filter((column) => !column.exportOnly && (column.key !== "obligor" || named) && (!textKeys || textKeys.includes(column.key))).map(plain),
+    ...(empty ? { empty } : {}) };
+}
+
+const CAPITAL: ExportColumn[] = [
+  { key: "name", header: "Instrument", minWidth: 20, textFormat: (value, row) => isClosed({ lifecycle: row.lifecycle as string | null }) ? `${value} (${row.lifecycle})` : String(value) },
+  { key: "lifecycle", header: "Status", exportOnly: true },
+  { key: "facilityType", header: "Type", format: (value) => value ? fieldLabel(String(value)) : NO_VALUE },
+  { key: "coupon", header: "Coupon/Margin" },
+  { key: "maturity", header: "Maturity" },
+  { key: "outstanding", header: "Outstanding", align: "right", textFormat: (value, row) => outstandingText(number(value), number(row.commitment)) },
+  { key: "commitment", header: "Commitment", align: "right", exportOnly: true },
+  { key: "currency", header: "CCY" },
+  { key: "ranking", header: "Rank", minWidth: 12 },
+  { key: "controlPut", header: "CoC put", align: "right" },
+  OBLIGOR,
+  INSTRUMENT_ID,
+];
+/** The pane's capital column behind each export column; the others are not in the pane's own list. */
+const PANE_COLUMN: Record<string, string> = { name: "name", facilityType: "facility", coupon: "coupon", maturity: "maturity", outstanding: "principal", currency: "currency", ranking: "ranking", controlPut: "control" };
+
+function capitalRows(data: CreditDocumentsPayload, instruments: readonly CreditInstrument[]): HeadlessPaneRow[] {
+  return instruments.map((row) => ({
+    name: row.name, lifecycle: row.lifecycle ?? null, facilityType: row.facilityType,
+    coupon: blank(capitalCell(row, "coupon", data)), maturity: row.maturity, outstanding: instrumentOutstanding(row), commitment: row.commitment,
+    currency: row.currency, ranking: blank(capitalCell(row, "ranking", data)), controlPut: blank(capitalCell(row, "control", data)),
+    obligor: name(row.obligor), instrumentId: row.id,
+  }));
+}
+/** The instruments as the Capital tab lists them; a column the pane leaves out as undisclosed stays out of the text report. */
+export function capitalSection(data: CreditDocumentsPayload, title = "Capital structure", instruments: readonly CreditInstrument[] = data.instruments): Section {
+  const shown = new Set(capitalColumns(data, Number.MAX_SAFE_INTEGER).map((column) => column.id));
+  return table(title, CAPITAL, capitalRows(data, instruments), { textKeys: CAPITAL.map((column) => column.key).filter((key) => !(key in PANE_COLUMN) || shown.has(PANE_COLUMN[key]!)) });
+}
+
+/** The unit a covenant row's figures are in, read from the fact its columns carry. */
+const figureUnit = (row: HeadlessPaneRow) => ({ unit: typeof row.unit === "string" ? row.unit : null, currency: typeof row.currency === "string" ? row.currency : null });
+const COVENANTS: ExportColumn[] = [
+  wide("metric", "Covenant"),
+  { key: "threshold", header: "Limit", align: "right", textFormat: (value, row) => `${comparatorSymbol(row.comparator as string, row.inclusive as boolean | null ?? undefined)} ${covenantNumber(number(value), figureUnit(row))}` },
+  { key: "comparator", header: "Comparator", exportOnly: true },
+  { key: "inclusive", header: "Inclusive", exportOnly: true },
+  { key: "unit", header: "Unit", exportOnly: true },
+  { key: "currency", header: "CCY", exportOnly: true },
+  { key: "current", header: "Reported", align: "right", textFormat: (value, row) => covenantNumber(number(value), figureUnit(row)) },
+  { key: "headroomPercent", header: "Headroom", align: "right", format: (value) => creditPercent(number(value)) },
+  { key: "status", header: "Status", format: (value) => fieldLabel(String(value)) },
+  { key: "asOf", header: "As of" },
+  { key: "testDate", header: "Test date", exportOnly: true },
+  wide("instrument", "Instrument"),
+  OBLIGOR,
+  { key: "reason", header: "Reason", underRow: true },
+  { key: "id", header: "Covenant ID", exportOnly: true },
+  { key: "instrumentId", header: "Instrument ID", exportOnly: true },
+];
+export function covenantSection(data: CreditDocumentsPayload): Section {
+  return table("Covenants", COVENANTS, data.covenants.map((row) => {
+    const fact = covenantFact(data, row);
+    return { metric: sentence(row.metric), threshold: row.threshold, comparator: row.comparator, inclusive: row.inclusive ?? null, unit: fact?.unit ?? null, currency: fact?.currency ?? null,
+      current: row.current, headroomPercent: row.headroomPercent, status: row.status, asOf: row.asOf, testDate: row.testDate, instrument: row.instrumentName,
+      obligor: name(row.obligor), reason: row.reason, id: row.id, instrumentId: row.instrumentId };
+  }));
+}
+
+function maturityColumns(preview: boolean): ExportColumn[] {
+  return [
+    { key: "year", header: "Year" },
+    { key: "currency", header: "CCY" },
+    { key: "principal", header: "Principal", align: "right", textFormat: (value) => creditAmount(number(value)) },
+    ...preview ? [] : [
+      { key: "share", header: "Share", align: "right", format: (value: unknown) => creditPercent(number(value)) } as ExportColumn,
+      { key: "cumulative", header: "Cumulative", align: "right", format: (value: unknown) => creditPercent(number(value)) } as ExportColumn,
+    ],
+    wide("instrument", "Instrument"),
+    OBLIGOR,
+    INSTRUMENT_ID,
+  ];
+}
+/** One row per instrument and year, in each currency: wall currencies are never added together. A preview wall is partial, so it has no shares. */
+export function maturitySection(data: CreditDocumentsPayload): Section {
+  const preview = data.access === "preview";
+  const rows = creditCurrencies(data).flatMap((currency) => {
+    const buckets = creditMaturityRows(data, currency), shares = preview ? new Map() : maturityShares(buckets);
+    return buckets.flatMap((bucket) => bucket.instruments.map((instrument) => {
+      const share = shares.get(`${bucket.year}:${instrument.id}`);
+      return { year: bucket.year, currency, principal: instrument.principal, ...preview ? {} : { share: share?.share ?? null, cumulative: share?.cumulative ?? null },
+        instrument: instrument.name, obligor: name(bucket.obligor), instrumentId: instrument.id };
+    }));
+  });
+  return table("Maturity wall", maturityColumns(preview), rows);
+}
+
+const CONTROL: ExportColumn[] = [
+  wide("instrument", "Instrument", { minWidth: 20 }),
+  { key: "putPercent", header: "Put", align: "right", format: (value) => value == null ? "" : `${value}%` },
+  { key: "principal", header: "Principal", align: "right", textFormat: (value) => creditAmount(number(value)) },
+  { key: "currency", header: "CCY" },
+  wide("trigger", "Trigger", { minWidth: 24 }),
+  OBLIGOR,
+  INSTRUMENT_ID,
+];
+export function controlSection(data: CreditDocumentsPayload): Section {
+  return table("Change of control", CONTROL, data.changeOfControl.map((row) => ({ instrument: row.instrumentName, putPercent: row.putPercent, principal: row.principal,
+    currency: row.currency, trigger: row.trigger, obligor: name(row.obligor), instrumentId: row.instrumentId })));
+}
+
+const SCREEN: ExportColumn[] = [
+  { key: "symbol", header: "Issuer" },
+  { key: "signal", header: "Signal" },
+  { key: "headroomPercent", header: "Headroom", align: "right", format: (value) => creditPercent(number(value)) },
+  { key: "date", header: "Date" },
+  wide("instrument", "Instrument", { minWidth: 20 }),
+  wide("condition", "Condition", { minWidth: 24 }),
+  { key: "currency", header: "CCY", exportOnly: true },
+  INSTRUMENT_ID,
+];
+/** The risk screen's signals as the Screen tab lists them; the evidence behind each stays behind `--instrument`. */
+export function screenSection(data: CreditScreenPayload): Section {
+  return table("Credit risk screen", SCREEN, data.rows.map((row) => ({ symbol: row.symbol, signal: screenSignal(row), headroomPercent: row.value, date: row.date, instrument: row.instrumentName,
+    condition: sentence(row.reason), currency: row.currency, instrumentId: row.instrumentId })));
+}
+
+const FACTS: ExportColumn[] = [
+  wide("term", "Term", { shrink: false }),
+  wide("value", "Disclosed value", { minWidth: 24 }),
+  { key: "amount", header: "Amount", exportOnly: true, align: "right" },
+  { key: "unit", header: "Unit", exportOnly: true },
+  { key: "asOf", header: "As of" },
+  { key: "filedAt", header: "Filed" },
+  { key: "status", header: "Revision", format: (value) => fieldLabel(String(value)) },
+  { key: "form", header: "Form", exportOnly: true },
+  { key: "confidence", header: "Confidence", exportOnly: true, align: "right" },
+  { key: "filingUrl", header: "Filing URL", exportOnly: true },
+  { key: "id", header: "Fact ID", exportOnly: true },
+  // The filing's own words belong to the instrument view; the text report prints them under their term.
+  { key: "quote", header: "Filing text", underRow: true },
+];
+const factRow = (fact: CreditFact): HeadlessPaneRow => ({ term: fieldLabel(fact.field), value: factValue(fact), amount: number(fact.value), unit: fact.currency ?? fact.unit, asOf: fact.asOf, filedAt: fact.filedAt, status: fact.status,
+  form: fact.form, confidence: fact.confidence, filingUrl: fact.filingUrl, id: fact.id, quote: fact.quote });
+/** An instrument's terms and amendments, each with the filing text behind it. Current terms are all in effect, so only the history names the revision. */
+export function instrumentSections(data: CreditDocumentsPayload, instrument: CreditInstrument): Section[] {
+  const byTerm = (a: CreditFact, b: CreditFact) => a.field.localeCompare(b.field) || a.factKey.localeCompare(b.factKey);
+  const history = [...instrument.history ?? []].sort((a, b) => b.filedAt.localeCompare(a.filedAt) || a.field.localeCompare(b.field));
+  return [
+    capitalSection(data, instrument.name, [instrument]),
+    table("Current terms", FACTS, [...instrument.facts].sort(byTerm).map(factRow), { textKeys: FACTS.map((column) => column.key).filter((key) => key !== "status") }),
+    table("Amendment history", FACTS, history.map(factRow)),
+  ];
+}

package/src/plugins/builtin/credit-documents/headless.ts

@@ -1,7 +1,8 @@
 import type { HeadlessPaneDefinition } from "../../../types/plugin";
 import type { CreditDocumentsPayload } from "../../../api-client/credit-documents";
 import { creditIssuerSymbol, fetchCreditDocuments, fetchCreditInstrument, fetchCreditScreen } from "./client";
-import { CREDIT_TABS } from "./model";
+import { capitalSection, controlSection, covenantSection, instrumentSections, maturitySection, screenSection } from "./export";
+import { CREDIT_TABS, creditEmptyCause } from "./model";
 import { SEC_FILINGS } from "../shared/report-freshness";
 
 export const creditHeadless: HeadlessPaneDefinition<"bundle"> = {
@@ -25,19 +26,18 @@ export const creditHeadless: HeadlessPaneDefinition<"bundle"> = {
     if (args.options.tab === "screen") {
       const data = await fetchCreditScreen({ headroomBelow: Number(args.options.headroom ?? 20), springingWithinMonths: Number(args.options.months ?? 12), limit: 100 }, ctx.apiClient);
       return { complete: data.lockedRows === 0 && !data.truncated, errors: [...(data.lockedRows ? ["More results require Gloom Pro"] : []), ...(data.truncated ? ["Screen reached the result limit"] : [])],
-        sections: [{ title: "Credit risk screen", rows: data.rows.map((row) => ({ ...row })) }], metadata: { asOf: data.asOf, access: data.access, lockedRows: data.lockedRows } };
+        sections: [screenSection(data)], metadata: { asOf: data.asOf, access: data.access, lockedRows: data.lockedRows } };
     }
     const data = await fetchCreditDocuments(args.symbols[0]!, ctx.apiClient);
     const instrument = args.options.instrument ? await fetchCreditInstrument(data.symbol, String(args.options.instrument), ctx.apiClient) : null;
     const reason = instrument ? null : creditEmptyReason(data, args.symbols[0]!);
-    // Nothing on file says why once, instead of four empty sections.
+    // Nothing on file says why once, as the report's one reason, instead of four empty sections and a generic "not covered".
     if (reason) {
-      return { complete: false, errors: data.warnings, sections: [],
-        metadata: { symbol: data.symbol, issuer: data.issuer, asOf: data.asOf, access: data.access, lockedRows: data.lockedRows, status: data.status, reason, notices: [reason] } };
+      return { complete: false, errors: data.warnings, sections: [], empty: reason,
+        metadata: { symbol: data.symbol, issuer: data.issuer, asOf: data.asOf, access: data.access, lockedRows: data.lockedRows, status: data.status, reason } };
     }
     return { complete: data.status === "available" && data.lockedRows === 0, errors: [...data.warnings, ...(data.lockedRows ? ["Full credit documents and history require Gloom Pro"] : [])],
-      sections: instrument ? [{ title: instrument.name, rows: [{ ...instrument }] }, { title: "Current terms", rows: instrument.facts.map((row) => ({ ...row })) }, { title: "Amendment history", rows: (instrument.history ?? []).map((row) => ({ ...row })) }]
-        : [{ title: "Capital structure", rows: data.instruments.map((row) => ({ ...row })) }, { title: "Covenants", rows: data.covenants.map((row) => ({ ...row })) }, { title: "Maturity wall", rows: data.maturities.map((row) => ({ ...row })) }, { title: "Change of control", rows: data.changeOfControl.map((row) => ({ ...row })) }],
+      sections: instrument ? instrumentSections(data, instrument) : [capitalSection(data), covenantSection(data), maturitySection(data), controlSection(data)],
       metadata: { symbol: data.symbol, issuer: data.issuer, asOf: data.asOf, access: data.access, lockedRows: data.lockedRows, status: data.status } };
   },
 };
@@ -55,10 +55,10 @@ export function creditEmptyReason(
   data: Pick<CreditDocumentsPayload, "symbol" | "issuer" | "instruments" | "covenants" | "maturities" | "changeOfControl" | "lockedRows">,
   requested: string,
 ): string | null {
-  const rows = data.instruments.length + data.covenants.length + data.maturities.length + data.changeOfControl.length;
-  if (rows > 0 || data.lockedRows > 0) return null;
+  const cause = creditEmptyCause(data);
+  if (!cause) return null;
   const symbol = requested.trim().toUpperCase();
-  const why = data.issuer
+  const why = cause === "instruments" && data.issuer
     ? `No credit documents on file for ${data.issuer.name} (${symbol}): no debt instrument has been read from its filings yet.`
     : `No credit documents on file for ${symbol}: it is not an issuer the credit-document set covers.`;
   const example = creditIssuerSymbol(symbol) === CREDIT_EXAMPLE_SYMBOL ? "" : ` Try \`gloom fn CRDOC ${CREDIT_EXAMPLE_SYMBOL}\` for an issuer with documents.`;

package/src/plugins/builtin/credit-documents/model.ts

@@ -54,12 +54,14 @@ function structuredSummary(fact: CreditFact): string | null {
   const low = finite(value.minimum), high = finite(value.maximum);
   return low !== null && high !== null ? [`${low}–${high}${unitSuffix(fact.unit)}`, words(value.condition)].filter(Boolean).join(" · ") : null;
 }
+const VALUE_KINDS = new Set(["text", "date"]);
 export function factValue(fact: CreditFact): string {
   if (typeof fact.value === "number" && ["percent", "%"].includes(fact.unit ?? "")) return `${fact.value}%`;
   const summary = structuredSummary(fact);
   if (summary) return summary;
   const value = typeof fact.value === "number" && fact.currency ? creditAmount(fact.value) : typeof fact.value === "string" ? sentence(fact.value) : creditValue(fact.value);
-  return [value, fact.currency ?? fact.unit].filter(Boolean).join(" ");
+  // `text` and `date` say what kind of value a fact holds, not what it is measured in.
+  return [value, fact.currency ?? (fact.unit && !VALUE_KINDS.has(fact.unit) ? fact.unit : null)].filter(Boolean).join(" ");
 }
 
 export interface CreditTermField { label: string; value: string; detail?: string }
@@ -98,13 +100,34 @@ function instrumentFact(row: CreditInstrument, field: string): CreditFact | unde
   return row.facts.find((fact) => fact.field === field);
 }
 const CLOSED = new Set(["repaid", "redeemed", "terminated", "cancelled", "matured"]);
-export const isClosed = (row: CreditInstrument) => !!row.lifecycle && CLOSED.has(row.lifecycle);
+export const isClosed = (row: Pick<CreditInstrument, "lifecycle">) => !!row.lifecycle && CLOSED.has(row.lifecycle);
 /** What is owed now: a revolver's drawn balance, otherwise outstanding principal. */
 export const instrumentOutstanding = (row: CreditInstrument) => row.drawn ?? row.principal;
-const creditCoupon = (row: CreditInstrument) => {
+/** A margin in basis points, from the unit the filing states it in; null when the unit does not say. */
+function marginBasisPoints(margin: CreditFact): number | null {
+  const value = finite(margin.value);
+  if (value === null) return null;
+  if (margin.unit === "bps" || margin.unit === "bp") return value;
+  return margin.unit === "percent" || margin.unit === "%" ? Number((value * 100).toFixed(2)) : null;
+}
+/** SOFR is written `S`, as a floating spread is quoted; any other named base keeps its name. */
+const baseLabel = (reference: string) => /\bSOFR\b/i.test(reference) ? "S" : reference;
+/**
+ * What an instrument pays: a fixed coupon as its percentage, a floating margin
+ * as its spread over the base in basis points (`S+148`, `EURIBOR+175`). A
+ * margin with no named base is read as SOFR for a dollar or undated currency
+ * instrument, the market's base for dollar loans, and is left bare for any other.
+ */
+export function creditCoupon(row: CreditInstrument): string {
   const coupon = instrumentFact(row, "coupon"), margin = instrumentFact(row, "margin"), reference = instrumentFact(row, "reference_rate");
-  return coupon ? factValue(coupon) : [reference ? creditValue(reference.value) : null, margin ? factValue(margin) : null].filter(Boolean).join(" + ") || NO_VALUE;
-};
+  const named = reference ? words(typeof reference.value === "string" ? reference.value : creditValue(reference.value)) : null;
+  if (margin) {
+    const base = named ? baseLabel(named) : !row.currency || row.currency === "USD" ? "S" : "";
+    const basisPoints = marginBasisPoints(margin);
+    return basisPoints === null ? `${base}+${factValue(margin)}` : `${base}${basisPoints < 0 ? "-" : "+"}${Math.abs(basisPoints)}`;
+  }
+  return coupon ? factValue(coupon) : named ?? NO_VALUE;
+}
 const rankText = (row: CreditInstrument) => {
   const fact = instrumentFact(row, "ranking") ?? instrumentFact(row, "security");
   return fact ? sentence(creditValue(fact.value)) : NO_VALUE;
@@ -114,6 +137,74 @@ function securityClass(row: CreditInstrument): "secured" | "unsecured" | null {
   const text = ["ranking", "security"].map((field) => { const fact = instrumentFact(row, field); return fact ? creditValue(fact.value).toLowerCase() : ""; }).join(" ");
   return /\bunsecured\b/.test(text) ? "unsecured" : /\bsecured\b/.test(text) ? "secured" : null;
 }
+const reasonKey = (text: string) => text.trim().replace(/\.$/, "").toLowerCase();
+/**
+ * The phrases the headroom check gives for a covenant it cannot compute, in plain
+ * words. The payload carries the phrase and no code, so each is matched whole.
+ * An empty line says nothing more than the missing figure, which comes first.
+ */
+const PLAIN_REASONS: Record<string, string | ((limit: string) => string)> = {
+  "covenant boundary inclusivity is not established": (limit) => `The filing doesn't say if exactly ${limit} passes.`,
+  "springing test; activation conditions require review": "Only tested once a trigger is met; the filing's trigger needs a read.",
+  "covenant adjustments are not fully disclosed": "The filing does not spell out how the ratio is adjusted.",
+  "no reported value for this covenant definition": "",
+  "reported metric units or currency do not match the covenant": "The reported figure is in other units than the limit.",
+  "reported metric definition or borrower scope does not match the covenant": "The reported figure is defined differently from the covenant's ratio.",
+  "latest comparable financials are more than 190 days old": "The latest comparable financials are over 190 days old.",
+  "financial period is in the future": "The comparable financials are dated in the future.",
+  "financial period does not match the covenant test date": "The reported period is not the covenant's test date.",
+  "a positive threshold is required to express percentage headroom": "Percentage headroom needs a limit above zero.",
+};
+/**
+ * Why a covenant has no headroom, in a few plain words, or null when it has a
+ * figure or no reason. The missing reported figure comes first when the
+ * instrument's facts hold none for this covenant's metric; then what the
+ * covenant's own terms or the check say. A step-up in the filing's adjustment
+ * text is named with its limit. A phrase not known here is the payload's own,
+ * as it came.
+ */
+export function covenantReason(row: Pick<CreditHeadroom, "id" | "status" | "reason" | "metric" | "threshold">, facts: readonly CreditFact[]): string | null {
+  const raw = row.status === "compliant" || row.status === "breach" ? null : row.reason?.trim();
+  if (!raw) return null;
+  const fact = facts.find((entry) => entry.id === row.id);
+  const limit = covenantNumber(row.threshold, fact);
+  const known = PLAIN_REASONS[reasonKey(raw)];
+  const reported = facts.some((entry) => entry.field === "reported_metric" && reasonKey(reportedMetricName(entry)) === reasonKey(row.metric));
+  // Said only with the instrument's facts in hand: with none loaded, there is nothing to show it has no figure.
+  const lead = known === "" || (facts.length > 0 && !reported) ? `No reported ${row.metric.trim()} to compare yet.` : null;
+  const stepUp = /step[- ]?up to ([\d.]+)/i.exec(raw);
+  let why: string | null;
+  if (typeof known === "function") why = known(limit);
+  else if (known !== undefined) why = known || null;
+  else if (stepUp) why = `The ${limit} limit can step up to ${covenantNumber(Number(stepUp[1]), fact)}${/acquisition/i.test(raw) ? " after permitted acquisitions" : " under conditions in the filing"}.`;
+  else why = `${sentence(raw)}${/[.!?]$/.test(raw) ? "" : "."}`;
+  return [lead, why].filter(Boolean).join(" ");
+}
+/** The metric a reported-figure fact is for, from its structured value. */
+function reportedMetricName(fact: CreditFact): string {
+  return words(fields(fact.value)?.metric) ?? "";
+}
+/** What an issuer with no rows at all lacks: the issuer itself, or a debt instrument read from its filings. */
+type CreditEmptyCause = "issuer" | "instruments";
+/**
+ * Why a payload has nothing to show in any section. Null when a section has a
+ * row, or Pro holds some back: a preview that is partly locked is not empty.
+ */
+export function creditEmptyCause(data: Pick<CreditDocumentsPayload, "issuer" | "instruments" | "covenants" | "maturities" | "changeOfControl" | "lockedRows">): CreditEmptyCause | null {
+  const rows = data.instruments.length + data.covenants.length + data.maturities.length + data.changeOfControl.length;
+  return rows > 0 || data.lockedRows > 0 ? null : data.issuer ? "instruments" : "issuer";
+}
+/** The pane's line for an empty payload; the CLI says the same with the issuer's name. */
+export const CREDIT_EMPTY_TITLE: Record<CreditEmptyCause, string> = {
+  instruments: "No debt instrument has been read from this issuer's filings yet.",
+  issuer: "This is not an issuer the credit documents cover.",
+};
+/** The maintenance covenant fact a headroom row was computed from, which says its unit. */
+export const covenantFact = (data: Pick<CreditDocumentsPayload, "instruments">, row: Pick<CreditHeadroom, "id" | "instrumentId">): CreditFact | undefined =>
+  data.instruments.find((item) => item.id === row.instrumentId)?.facts.find((item) => item.id === row.id);
+/** What a screen row flags, in the words the pane and its exports use. */
+export const screenSignal = (row: Pick<CreditScreenRow, "kind" | "value">) =>
+  row.kind === "springing_maturity" ? "Springing maturity" : row.value != null && row.value < 0 ? "Breach" : "Low headroom";
 export const screenRowId = (row: CreditScreenRow) => `${row.symbol}:${row.instrumentId}:${row.kind}:${row.date ?? ""}:${row.reason}`;
 /** Wall currencies, the one with the most instruments first so the wall opens on the issuer's main debt. */
 export function creditCurrencies(data: CreditDocumentsPayload): string[] {
@@ -208,14 +299,14 @@ type CapitalColumnId = "name" | "facility" | "coupon" | "maturity" | "principal"
 const CAPITAL_COLUMNS: Column<CapitalColumnId>[] = [
   { id: "name", label: "Instrument", width: 24, flexGrow: 1, align: "left" },
   { id: "facility", label: "Type", width: 12, align: "left" },
-  { id: "coupon", label: "Coupon", width: 20, align: "left" },
+  { id: "coupon", label: "Coupon/Margin", width: 20, align: "left" },
   { id: "maturity", label: "Maturity", width: 10, align: "left" },
   { id: "principal", label: "Outstanding", width: 11, align: "right" },
   { id: "currency", label: "CCY", width: 3, align: "left" },
   { id: "ranking", label: "Rank", width: 26, align: "left" },
   { id: "control", label: "CoC put", width: 7, align: "right" },
 ];
-/** Text columns take the width their values need, up to the column's own width. */
+/** Text columns take the width their values and their label need, up to the column's own width. */
 const FITTED_CAPITAL = new Set<CapitalColumnId>(["facility", "coupon", "ranking"]);
 const SPARSE_CAPITAL = new Set<CapitalColumnId>(["ranking", "control"]);
 export function capitalColumns(data: CreditDocumentsPayload, width: number): DataTableColumn[] {
@@ -223,20 +314,19 @@ export function capitalColumns(data: CreditDocumentsPayload, width: number): Dat
   const disclosed = (id: CapitalColumnId) => rows.filter((row) => capitalCell(row, id, data) !== NO_VALUE).length;
   // A column nothing discloses is left out; ranking and puts need most instruments.
   const columns = CAPITAL_COLUMNS.filter((column) => column.id === "name" || column.id === "principal" || (SPARSE_CAPITAL.has(column.id) ? disclosed(column.id) * 2 > rows.length : disclosed(column.id) > 0))
-    .map((column) => FITTED_CAPITAL.has(column.id) ? { ...column, width: Math.min(column.width, Math.max(4, ...rows.map((row) => displayWidth(capitalCell(row, column.id, data))))) } : column);
+    .map((column) => FITTED_CAPITAL.has(column.id) ? { ...column, width: Math.min(column.width, Math.max(4, displayWidth(column.label), ...rows.map((row) => displayWidth(capitalCell(row, column.id, data))))) } : column);
   // One currency is said by the figures; several keep their column at every width.
   const single = new Set(rows.map((row) => row.currency).filter(Boolean)).size <= 1;
   return fitColumns(columns, width, ["control", "ranking", ...(single ? ["currency" as const] : []), "facility", "coupon", "maturity"]);
 }
+/** A revolver reads as drawn of commitment; the strip carries the undrawn total. */
+export const outstandingText = (outstanding: number | null, commitment: number | null): string =>
+  commitment != null && commitment !== outstanding ? `${creditAmount(outstanding)} of ${creditAmount(commitment)}` : creditAmount(outstanding);
 export function capitalCell(row: CreditInstrument, column: string, data: CreditDocumentsPayload): string {
   const control = data.changeOfControl.find((entry) => entry.instrumentId === row.id);
   switch (column) {
     case "name": return isClosed(row) ? `${row.name} (${row.lifecycle})` : row.name;
-    case "principal": {
-      // A revolver reads as drawn of commitment; the strip carries the undrawn total.
-      const outstanding = creditAmount(instrumentOutstanding(row));
-      return row.commitment != null && row.commitment !== instrumentOutstanding(row) ? `${outstanding} of ${creditAmount(row.commitment)}` : outstanding;
-    }
+    case "principal": return outstandingText(instrumentOutstanding(row), row.commitment);
     case "currency": return row.currency ?? NO_VALUE;
     case "maturity": return row.maturity ?? NO_VALUE;
     case "coupon": return creditCoupon(row);
@@ -320,7 +410,7 @@ export function maturityAxis(rows: readonly CreditMaturityBucket[]) {
 }
 
 /** The source fact, not the magnitude, determines a covenant's unit. */
-export function covenantNumber(value: number | null, fact: CreditFact | undefined): string {
+export function covenantNumber(value: number | null, fact: Pick<CreditFact, "currency" | "unit"> | undefined): string {
   if (value === null) return NO_VALUE;
   if (fact?.currency) return `${creditAmount(value)} ${fact.currency}`;
   if (fact?.unit === "ratio" || fact?.unit === "times") return `${value}x`;

package/src/plugins/builtin/credit-documents/pane.tsx

@@ -2,7 +2,7 @@ import { useCallback, useMemo } from "react";
 import { isAccessDenied } from "../../../api-client/errors";
 import { usePlanAccess } from "../../../api-client/plan-access";
 import type { CreditDocumentsPayload, CreditHeadroom, CreditInstrument, CreditScreenPayload, CreditScreenRow } from "../../../api-client/credit-documents";
-import { ChartTableHeader, DataTableView, EmptyState, PageStackView, QueryBar, useChartTableSelection, usePaneFooter, usePaneNoticeFooter, usePaneStatusFooter, usePaneTabs, type DataTableCell, type DataTableColumn, type PaneHint } from "../../../components";
+import { ChartTableHeader, DataTableView, EmptyState, Notice, PageStackView, QueryBar, useChartTableSelection, usePaneFooter, usePaneNoticeFooter, usePaneStatusFooter, usePaneTabs, type DataTableCell, type DataTableColumn, type PaneHint } from "../../../components";
 import { formatCompactAxis } from "../../../components/chart-table";
 import { usePaneRefreshKey } from "../../../components/data-table/table-pane";
 import { useAsyncResource, useAutoRefresh, usePaneSettingValue, usePluginAppActions, usePluginPaneState } from "../../../public/react";
@@ -19,7 +19,7 @@ import { cachedCredit, creditIssuerSymbol, CREDIT_UNAVAILABLE, fetchCreditScreen
 import { CreditInstrumentDetail } from "./detail";
 import { useCreditEvidence } from "./evidence";
 import { HeadroomGauge } from "./gauge";
-import { capitalCell, capitalColumns, capitalFigures, comparatorSymbol, covenantColumns, covenantUsage, CREDIT_TABS, creditAmount, covenantNumber, creditCurrencies, creditMaturityRows, creditPercent, creditTab, fieldLabel, headroomTone, instrumentOutstanding, isClosed, maturityAxis, maturityColumns, maturitySeries, maturityShares, NO_VALUE, screenColumns, screenRowId, sentence } from "./model";
+import { capitalCell, capitalColumns, capitalFigures, comparatorSymbol, covenantColumns, covenantFact, covenantReason, covenantUsage, CREDIT_EMPTY_TITLE, creditEmptyCause, CREDIT_TABS, creditAmount, covenantNumber, creditCurrencies, creditMaturityRows, creditPercent, creditTab, fieldLabel, headroomTone, instrumentOutstanding, isClosed, maturityAxis, maturityColumns, maturitySeries, maturityShares, NO_VALUE, screenColumns, screenRowId, screenSignal, sentence } from "./model";
 
 type Row = { numbers?: Record<string, number | null>; id: string; values: Record<string, string>; instrumentId?: string; covenant?: CreditHeadroom; screen?: CreditScreenRow; year?: number; locked?: boolean; closed?: boolean };
 const rowId = (row: Row) => row.id;
@@ -70,10 +70,10 @@ function CreditView({ symbol, width, height, focused, accessKey, needsVerificati
     : tab === "maturities" ? maturityColumns(width, preview) : screenColumns(width), [tab, data, width, preview]);
   const figures = useMemo(() => tab === "capital" && data ? capitalFigures(data) : [], [tab, data]);
   const unsortedRows = useMemo<Row[]>(() => {
-    if (tab === "screen") return (screenData?.rows ?? []).map((row) => ({ id: screenRowId(row), instrumentId: row.instrumentId, screen: row, numbers: {value:row.value}, values: { symbol: row.symbol, kind: row.kind === "springing_maturity" ? "Springing maturity" : row.value != null && row.value < 0 ? "Breach" : "Low headroom", value: creditPercent(row.value), date: row.date ?? NO_VALUE, instrument: row.instrumentName, reason: sentence(row.reason) } }));
+    if (tab === "screen") return (screenData?.rows ?? []).map((row) => ({ id: screenRowId(row), instrumentId: row.instrumentId, screen: row, numbers: {value:row.value}, values: { symbol: row.symbol, kind: screenSignal(row), value: creditPercent(row.value), date: row.date ?? NO_VALUE, instrument: row.instrumentName, reason: sentence(row.reason) } }));
     if (!data) return [];
     if (tab === "capital") return data.instruments.map((row) => ({ id: row.id, instrumentId: row.id, closed: isClosed(row), numbers: {principal:instrumentOutstanding(row)}, values: Object.fromEntries(["name", "facility", "coupon", "maturity", "principal", "currency", "ranking", "control"].map((id) => [id, capitalCell(row, id, data)])) }));
-    if (tab === "covenants") return data.covenants.map((row) => { const fact=data.instruments.find((item) => item.id === row.instrumentId)?.facts.find((item) => item.id === row.id); return ({ id: row.id, instrumentId: row.instrumentId, covenant: row, numbers: {headroom:row.headroomPercent,usage:covenantUsage(row),threshold:row.threshold,current:row.current}, values: { metric: sentence(row.metric), headroom: creditPercent(row.headroomPercent), usage: "", threshold: `${comparatorSymbol(row.comparator, row.inclusive)} ${covenantNumber(row.threshold,fact)}`, current: covenantNumber(row.current,fact), status: fieldLabel(row.status), date: row.asOf, instrument: row.instrumentName } }); });
+    if (tab === "covenants") return data.covenants.map((row) => { const fact=covenantFact(data, row); return ({ id: row.id, instrumentId: row.instrumentId, covenant: row, numbers: {headroom:row.headroomPercent,usage:covenantUsage(row),threshold:row.threshold,current:row.current}, values: { metric: sentence(row.metric), headroom: creditPercent(row.headroomPercent), usage: "", threshold: `${comparatorSymbol(row.comparator, row.inclusive)} ${covenantNumber(row.threshold,fact)}`, current: covenantNumber(row.current,fact), status: fieldLabel(row.status), date: row.asOf, instrument: row.instrumentName } }); });
     const shares = preview ? new Map() : maturityShares(maturityRows);
     return maturityRows.flatMap((row) => row.instruments.map((instrument) => { const id = `${row.year}:${instrument.id}`, share = shares.get(id); return { id, instrumentId: instrument.id, year: row.year, numbers: {year:row.year,principal:instrument.principal,share:share?.share ?? null,cumulative:share?.cumulative ?? null}, values: { year: String(row.year), principal: creditAmount(instrument.principal), share: creditPercent(share?.share), cumulative: creditPercent(share?.cumulative), instruments: instrument.name } }; }));
   }, [data, screenData, tab, maturityRows, preview]);
@@ -85,11 +85,17 @@ function CreditView({ symbol, width, height, focused, accessKey, needsVerificati
       : left === right ? a.id.localeCompare(b.id) : (left < right ? -1 : 1)*(sort.direction === "asc" ? 1 : -1);
   }),[unsortedRows,sort]);
   const selected = rows.find((row) => row.id === selectedId) ?? rows[0] ?? null;
+  // The status says Uncomputable; the selected row says why, on the row, as the detail does.
+  const selectedCovenant = tab === "covenants" ? selected?.covenant : undefined;
+  const whyNoHeadroom = selectedCovenant ? covenantReason(selectedCovenant, data?.instruments.find((row) => row.id === selectedCovenant.instrumentId)?.facts ?? []) : null;
   const screenOpen = rows.find((row) => row.id === openId)?.screen;
   const openInstrument = data?.instruments.find((row) => row.id === openId) ?? (screenOpen ? { id: screenOpen.instrumentId, key: screenOpen.instrumentId, name: screenOpen.instrumentName, currency: screenOpen.currency, facilityType: null, principal: null, commitment: null, drawn: null, maturity: null, facts: screenOpen.evidence } : null);
   const [initialFact] = usePaneSettingValue<string | null>("fact", null);
   const [openFactId, setOpenFact] = usePluginPaneState<string | null>(`credit:fact:open:${openInstrument?.id ?? "none"}`, initialFact);
   const activeSymbol = screenOpen?.symbol ?? symbol;
+  // An issuer with nothing in any section says why once, in each tab, instead of a different empty line per tab.
+  const emptyCause = data ? creditEmptyCause(data) : null;
+  const nothingOnFile = emptyCause ? CREDIT_EMPTY_TITLE[emptyCause] : null;
   const activeCovenant = tab === "covenants" ? data?.covenants.find((row) => row.id === selected?.id && row.instrumentId === openInstrument?.id) ?? null : null;
   const locked = tab === "screen" ? screenData?.lockedRows ?? 0 : data?.lockedRows ?? 0;
   const items = useMemo<Row[]>(() => [...rows, ...Array.from({ length: Math.min(3, locked) }, (_, index) => ({ id: `locked:${index}`, values: {}, locked: true }))], [rows, locked]);
@@ -180,7 +186,8 @@ function CreditView({ symbol, width, height, focused, accessKey, needsVerificati
           getItemKey={rowId} selection={{ kind: "id", selectedId: selected?.id ?? null, getId: rowId, onChange: setSelected }}
           onActivate={(row) => row.locked ? openUpgrade() : setOpen(row.screen ? row.id : row.instrumentId ?? null)}
           renderCell={renderCell}
-          emptyStateTitle={tab === "screen" ? "No supported credit signals match these thresholds." : tab === "covenants" ? "No financial maintenance covenants documented." : tab === "maturities" ? "No supported instrument maturity amounts." : CREDIT_UNAVAILABLE}
+          emptyStateTitle={tab === "screen" ? "No supported credit signals match these thresholds." : nothingOnFile ?? (tab === "covenants" ? "No financial maintenance covenants documented." : tab === "maturities" ? "No supported instrument maturity amounts." : CREDIT_EMPTY_TITLE.instruments)}
+          rootAfter={whyNoHeadroom ? <Box paddingX={1} flexShrink={0}><Notice tone="muted">{whyNoHeadroom}</Notice></Box> : undefined}
           emptyStateHint={tab === "screen" && (headroom < 100 || months < 36) ? "Raise either threshold to widen the screen." : undefined}
           selectedTextOverridesCellColor showHorizontalScrollbar freezeFirstColumn resetScrollKey={`${symbol}:${tab}:${selectedCurrency}`}
           bodyAfter={locked > 0 && desktop ? <LockedOverlay rows={Math.min(3, locked)} text={lockedText} onPress={openUpgrade} /> : undefined} />} />

package/src/plugins/builtin/custom-view/sources.ts

@@ -30,6 +30,8 @@ export function listViewSources(catalog: ViewSourceCatalog): ViewSourceInfo[] {
     const pane = catalog.panes.get(template.paneId);
     if (!pane) continue;
     templated.add(pane.id);
+    // An unlisted function (`listed: false`) is not offered, nor its pane in its place.
+    if (template.listed === false) continue;
     const headless = template.headless ?? pane.headless;
     if (!headless) continue;
     sources.push({