gloomberb 0.16.3 → 0.16.5

package/src/plugins/builtin/short-volume/index.tsx

@@ -1,9 +1,7 @@
 import type { PaneInstanceConfig } from "../../../types/config";
 import type { PluginModule } from "../plugin-module";
-import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
+import { SHORT_VOLUME_SERIES } from "./series";
 import { shortVolumeCache } from "./client";
-import { shortVolumeHeadless } from "./headless";
-import { ShortVolumePane } from "./pane";
 
 export const shortVolumeSettings = [
   { key: "shortVolumeScope", label: "Reporting scope", type: "select" as const,
@@ -14,14 +12,9 @@ export const shortVolumeSettings = [
 export const followsWithoutFinraOverride = (pane: PaneInstanceConfig) => (
   typeof pane.settings?.finraSymbol !== "string" || !pane.settings.finraSymbol.trim()
 );
+/** The daily-volume cache. `SIV` opens the short interest pane, so this module has no pane of its own. */
 export const shortVolumeModule: PluginModule = {
-  panes: [{ id: "short-volume", name: "Daily Short Volume", icon: "S", component: ShortVolumePane,
-    defaultPosition: "right", tickerFollower: followsWithoutFinraOverride, defaultMode: "floating", defaultFloatingSize: { width: 92, height: 28 },
-    tableExport: true, headless: shortVolumeHeadless, settings: { title: "Daily Short Volume", fields: shortVolumeSettings } }],
-  paneTemplates: [{ ...createTickerSurfacePaneTemplate({ id: "short-volume-pane", paneId: "short-volume", label: "Daily Short Volume",
-    description: "FINRA daily off-exchange short-volume ratios, historical percentile and reported share quantities.",
-    shortcut: "SIV", keywords: ["daily", "short", "volume", "finra", "siv"], publicShare: true,
-  }), headless: shortVolumeHeadless }],
+  series: SHORT_VOLUME_SERIES,
   setup(ctx) { shortVolumeCache.attach(ctx.persistence); },
   dispose() { shortVolumeCache.reset(); },
 };

package/src/plugins/builtin/short-volume/series.ts

@@ -0,0 +1,23 @@
+import type { SeriesDefinition } from "../../../series/types";
+import { cachedSeriesWarning } from "../shared/series-warning";
+import { loadShortVolume } from "./client";
+
+/** The share of a ticker's daily on-exchange volume reported as short sales. */
+export const SHORT_VOLUME_SERIES: readonly SeriesDefinition[] = [{
+  id: "short-volume:ratio",
+  name: "Daily short volume ratio",
+  unit: "%",
+  frequency: "daily",
+  group: "Positioning",
+  tags: ["short volume", "short sales", "shorts"],
+  publisher: "FINRA",
+  input: "ticker",
+  load: async ({ ticker }) => {
+    const resource = await loadShortVolume(ticker!, "nms");
+    const warning = cachedSeriesWarning(resource);
+    return {
+      points: resource.payload.history.map((point) => ({ date: point.date, value: point.ratioPercent })),
+      ...(warning ? { warning } : {}),
+    };
+  },
+}];

package/src/plugins/builtin/social-mentions/index.tsx

@@ -1,4 +1,5 @@
 import type { PluginModule } from "../plugin-module";
+import { SOCIAL_MENTION_SERIES } from "./series";
 import { createTickerSurfacePaneTemplate } from "../shared/ticker-surface";
 import { socialMentionPostsCache, socialMentionsCache } from "./client";
 import { socialMentionsHeadless } from "./headless";
@@ -9,6 +10,7 @@ const socialMentionsSettings = [
     options: [{ value: "1y", label: "1 year" }, { value: "5y", label: "5 years" }, { value: "max", label: "Since 2012" }] },
 ];
 export const socialMentionsModule: PluginModule = {
+  series: SOCIAL_MENTION_SERIES,
   panes: [{ id: "social-mentions", name: "Social Mentions", icon: "B", component: SocialMentionsPane,
     defaultPosition: "right", tickerFollower: true, defaultMode: "floating", defaultFloatingSize: { width: 96, height: 30 },
     tableExport: true, headless: socialMentionsHeadless, settings: { title: "Social Mentions", fields: socialMentionsSettings } }],

package/src/plugins/builtin/social-mentions/series.ts

@@ -0,0 +1,23 @@
+import type { SeriesDefinition } from "../../../series/types";
+import { cachedSeriesWarning } from "../shared/series-warning";
+import { loadSocialMentions } from "./client";
+
+/** How often a ticker is posted about each day, over the last year. */
+export const SOCIAL_MENTION_SERIES: readonly SeriesDefinition[] = [{
+  id: "social-mentions:posts",
+  name: "Social media mentions",
+  unit: "posts",
+  frequency: "daily",
+  group: "Alternative data",
+  tags: ["social", "mentions", "posts", "retail attention"],
+  input: "ticker",
+  style: "columns",
+  load: async ({ ticker }) => {
+    const resource = await loadSocialMentions(ticker!, "1y");
+    const warning = cachedSeriesWarning(resource);
+    return {
+      points: resource.payload.x.days.map((row) => ({ date: row.day, value: row.mentions })),
+      ...(warning ? { warning } : {}),
+    };
+  },
+}];

package/src/plugins/builtin/supply-chain/graph-pane.tsx

@@ -11,6 +11,7 @@ import { useThemeColors } from "../../../theme/theme-context";
 import { Box, ScrollBox, Text, TextAttributes, 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 { UpgradeLabel } from "../shared/locked-rows";
 import { isCloudSessionRequired, useResearchCloudSession } from "../shared/research-cloud-session";
 import { cachedGraph, graphOptions, loadGraph, validateGraph } from "./graph-client";
@@ -138,7 +139,7 @@ export function SupplyGraphPane({ symbol, tab, width, height, focused }: { symbo
   const selectedPath = paths.find(path => path.id === selectedPathId) ?? paths.find(path => path.nodeIds.at(-1) === selectedId) ?? (target ? initialPath : null) ?? null;
   const selected = (tab === "path" ? null : data?.nodes.find(node => node.id === selectedId)) ?? (selectedPath ? data?.nodes.find(node => node.id === selectedPath.nodeIds.at(-1)) : null) ?? null;
   const openPath = paths.find(path => path.id === openId) ?? (instance?.settings?.evidence && openId !== "closed" ? initialPath : null) ?? null;
-  const openUpgrade = useCloudUpgradeAction("splc"), { createPaneFromTemplate } = usePluginAppActions();
+  const openUpgrade = useCloudUpgradeAction("splc"), { createPaneFromTemplate } = usePluginAppActions(), openDescription = useOpenDescription();
   const recenter = (entity: SupplyEntity) => { setFocus(entityKey(entity)); setTarget(""); setTargetDraft(""); setSelected(null); setSelectedPath(null); setOpen(null); setCollapsed([]); };
   const applyTarget = (value: string) => { setTarget(value.trim()); setTargetDraft(value.trim()); setSelected(null); setSelectedPath(null); setOpen(null); setTargetActive(false); };
   const selectNode = (id: string) => { setSelected(id); setSelectedPath(null); };
@@ -149,7 +150,7 @@ export function SupplyGraphPane({ symbol, tab, width, height, focused }: { symbo
     ...(tab === "graph" && !openPath && selected && selected.id !== data?.entity?.id ? [{ id: "target", key: "p", label: "aths to target", onPress: () => applyTarget(entityKey(selected)) },
       { id: "collapse", key: "c", label: collapsed.includes(selected.id) ? "expand" : "ollapse", onPress: () => setCollapsed(old => old.includes(selected.id) ? old.filter(id => id !== selected.id) : [...old, selected.id]) }] : []),
     ...(!openPath && selected?.ticker ? [
-      { id: "description", key: "d", label: "es", onPress: () => createPaneFromTemplate("new-ticker-detail-pane", { symbol: entityKey(selected) }) },
+      { id: "description", key: "d", label: "es", onPress: () => openDescription(entityKey(selected)) },
       { id: "financials", key: "f", label: "a", onPress: () => createPaneFromTemplate("financial-analysis-pane", { symbol: entityKey(selected) }) },
       { id: "chart", key: "g", label: "raph", onPress: () => createPaneFromTemplate("chart-composer-pane", { arg: entityKey(selected) }) },
     ] : []),

package/src/plugins/builtin/supply-chain/model.ts

@@ -1,5 +1,5 @@
 import type { SupplyChainPayload, SupplyOptions, SupplyRole, SupplyRow } from "../../../api-client/supply-chain";
-import { SERIES_COLORS } from "../../../time-series/resolve";
+import { SERIES_COLORS } from "../../../theme/series-colors";
 import { revenueAmount } from "../revenue-breakdown/model";
 import { activeRelationship, corroborationLabel, evidenceDate, evidenceLabel, isUnconfirmed, matchesSupplyOptions, trustTier } from "./trust";
 

package/src/plugins/builtin/supply-chain/pane.tsx

@@ -19,6 +19,7 @@ import { Box, Text, TextAttributes, useRendererHost, useUiCapabilities } from ".
 import { displayWidth, truncateToDisplayWidth } from "../../../utils/format";
 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 { cachedSupplyChain, loadSupplyChain, SUPPLY_UNAVAILABLE, validateSupplyChain } from "./client";
@@ -143,6 +144,7 @@ function SupplyView({ symbol, width, height, focused }: Pick<PaneProps, "width"
   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"}`;
@@ -200,7 +202,7 @@ function SupplyView({ symbol, width, height, focused }: Pick<PaneProps, "width"
     ...(current ? [{ id: "source", key: "o", label: "pen source", onPress: () => void host.openExternal(current.filingUrl) }] : []),
     ...(!openRow && selected ? [{ id: "evidence", key: "e", label: "vidence", onPress: evidence }] : []),
     ...(selected?.counterparty.ticker ? [
-      { id: "description", key: "d", label: "es", onPress: () => navigate(selected, "new-ticker-detail-pane") },
+      { id: "description", key: "d", label: "es", onPress: () => openDescription(selected.counterparty.ticker!, selected.counterparty.exchange ?? undefined) },
       { id: "financials", key: "f", label: "a", onPress: () => navigate(selected, "financial-analysis-pane") },
       { id: "chart", key: "g", label: "raph", onPress: () => createPaneFromTemplate("chart-composer-pane", { arg: publicTickerKey(selected.counterparty.ticker!, selected.counterparty.exchange ?? undefined) }) },
       ...(getSharedRegistry()?.paneTemplates.has("buildout-pane") ? [{ id: "buildout", key: "t", label: "bo", onPress: () => createPaneFromTemplate("buildout-pane") }] : []),

package/src/plugins/builtin/thirteenf/api.ts

@@ -179,6 +179,7 @@ export function mapForm(raw: any): ThirteenFFormSummary | null {
     tableEntryTotal: finiteOrNull(raw.table_entry_total),
     isAmendment: boolOrFalse(raw.is_amendment) || submissionType.includes("/A"),
     amendmentType: stringOrEmpty(raw.amendment_type) || undefined,
+    valueNote: stringOrEmpty(raw.value_note) || undefined,
   };
 }
 

package/src/plugins/builtin/thirteenf/data.ts

@@ -14,6 +14,7 @@ import { isoDateDaysAgo, isoDateToday, isoDateYearsAgo } from "../../../utils/ca
 import {
   buildBrowserRows,
   latestLikely13FQuarter,
+  oneFundPerCik,
   buildPeriodReports,
   dedupeLatestForms,
 } from "./model";
@@ -192,7 +193,8 @@ async function loadBrowserPage(
       nextOffset: offset + 1,
     };
   }
-  const funds = await searchThirteenFFunds(trimmed, browserLimit, signal, pageApiOptions);
+  const found = await searchThirteenFFunds(trimmed, browserLimit, signal, pageApiOptions);
+  const funds = oneFundPerCik(found);
   const [{ reports, warning }, topFunds] = await Promise.all([
     loadReportsForFunds(funds.slice(0, Math.min(browserLimit, FORM_ENRICHMENT_LIMIT)), { from, to, signal, ...apiOptions }),
     listTopThirteenFFunds(quarter, browserLimit, signal, apiOptions).catch(() => []),
@@ -203,15 +205,15 @@ async function loadBrowserPage(
     .filter((fund): fund is ThirteenFTopFund => !!fund);
   return {
     rows: buildBrowserRows({
-      funds,
+      funds: oneFundPerCik(found, reports),
       topFunds: matchedTopFunds,
       reports,
       source: "funds",
     }),
     quarter,
     warning,
-    hasMore: funds.length >= browserLimit,
-    nextOffset: offset + funds.length,
+    hasMore: found.length >= browserLimit,
+    nextOffset: offset + found.length,
   };
 }
 

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

@@ -6,16 +6,30 @@ import type {
 } from "../../../types/plugin";
 import { formatShortDate } from "../../../utils/datetime-format";
 import { normalizeCik } from "./api";
-import { buildFundOverlap, overlapPeriod } from "./overlap";
+import { buildFundOverlap, buildManagerEtfOverlap, overlapPeriod } from "./overlap";
+import type { FundMembersPayload, MemberFundsPayload } from "../../../api-client/members";
+import { fetchFunds, fetchMembers } from "../members/client";
+import { coveredFund } from "../members/model";
 import { appendTickerHoldings, loadCrowding, loadTickerHoldings, type CrowdingRow, type TickerHoldings } from "./signals";
 import {
   AS_FILED_VALUE,
   compareCrowding,
   crowdingForTicker,
   cutText,
-  periodText,
+  filedPeriodText,
+  filingDayText,
+  filingLagDays,
+  isOptionType,
+  isStaleFiling,
+  markedPositionType,
+  OPTION_ROWS_NOTE,
+  restatedValuesText,
+  staleFilingText,
+  staleFundsText,
   summarizeTickerHoldings,
+  THIRTEENF_LIMITS,
   THIRTEENF_MAX_LIMIT,
+  THIRTEENF_OPTIONS_NOTE,
 } from "./report-notes";
 import {
   loadBrowserRows,
@@ -31,9 +45,9 @@ import {
   buildTimelineRows,
   inferBrowserTabFromQuery,
   hasComparable13FQuarter,
-  THIRTEENF_OPTIONS_NOTE,
   isCikQuery,
   positionType,
+  quartersBehindLatest,
   sortBrowserRows,
   sortHoldingRows,
   sortTimelineRows,
@@ -87,9 +101,16 @@ const BROWSER_COLUMNS: HeadlessPaneColumn[] = [
   },
 ];
 
+/** What a 13F position report notes after its table: the filing's limits, and what the option marker means when option rows are shown. */
+function positionNotes(rows: readonly { type?: unknown }[]): string[] {
+  return [THIRTEENF_LIMITS, ...(rows.some((row) => isOptionType(row.type)) ? [OPTION_ROWS_NOTE] : [])];
+}
+
+const TYPE_COLUMN: HeadlessPaneColumn = { key: "type", header: "Type", textFormat: markedPositionType };
+
 const HOLDING_COLUMNS: HeadlessPaneColumn[] = [
   { key: "ticker", header: "Ticker" },
-  { key: "type", header: "Type" },
+  TYPE_COLUMN,
   { key: "issuer", header: "Issuer" },
   {
     key: "value",
@@ -175,9 +196,13 @@ export interface ThirteenFHeadlessDependencies {
     args: HeadlessPaneLoadArgs,
     ctx: HeadlessPaneContext,
   ): Promise<FundDetailData>;
+  /** The ETFs whose holdings files MEMB serves. */
+  loadEtfFunds?(ctx: HeadlessPaneContext): Promise<MemberFundsPayload["funds"]>;
+  /** One covered ETF's holdings file, as `fn MEMB` reads it. */
+  loadEtfHoldings?(ticker: string, ctx: HeadlessPaneContext): Promise<FundMembersPayload>;
 }
 
-const defaultDependencies: ThirteenFHeadlessDependencies = {
+const defaultDependencies: Required<ThirteenFHeadlessDependencies> = {
   loadBrowser: (tab, query, limit, _args, ctx) => loadBrowserRows(
     tab,
     query,
@@ -185,6 +210,8 @@ const defaultDependencies: ThirteenFHeadlessDependencies = {
     { limit },
   ),
   loadDetail: (cik, name, _args, ctx) => loadFundDetail(cik, name, ctx.signal),
+  loadEtfFunds: async (ctx) => (await fetchFunds(ctx.apiClient)).funds,
+  loadEtfHoldings: (ticker, ctx) => fetchMembers(ticker, ctx.apiClient),
 };
 
 const VIEW_TITLES: Record<string, string> = {
@@ -217,18 +244,22 @@ function browserTab(view: HeadlessThirteenFView, query: string): ThirteenFBrowse
   return inferBrowserTabFromQuery(query);
 }
 
-async function resolveFund(
+/**
+ * The manager a fund name or CIK names: a CIK as given, else the one fund
+ * whose name matches exactly, else the only match. `search` lists funds by
+ * name, as the 13F browser does.
+ */
+async function findThirteenFFund(
   query: string,
-  args: HeadlessPaneLoadArgs,
-  ctx: HeadlessPaneContext,
-  dependencies: ThirteenFHeadlessDependencies,
-): Promise<{ cik: string; name: string }> {
-  if (!query) throw new Error("13F holdings and filings require a fund name or CIK.");
+  search: (query: string, limit: number) => Promise<BrowserLoadResult>,
+  { exactOnly = false }: { exactOnly?: boolean } = {},
+): Promise<{ cik: string; name: string } | null> {
   if (isCikQuery(query)) return { cik: normalizeCik(query), name: query };
   // A small output limit must not hide other matching managers during lookup.
-  const result = await dependencies.loadBrowser("funds", query, 25, args, ctx);
+  const result = await search(query, 25);
   const candidates = [...new Map(result.rows.map((row) => [row.cik, row])).values()];
   const exact = candidates.filter((row) => row.name.toLocaleLowerCase() === query.toLocaleLowerCase());
+  if (exactOnly) return exact.length === 1 ? { cik: exact[0]!.cik, name: exact[0]!.name } : null;
   const fund = exact.length === 1 ? exact[0]
     : candidates.length === 1 && !result.hasMore ? candidates[0] : undefined;
   if (candidates.length === 0) throw new Error(`No 13F fund found for "${query}".`);
@@ -239,12 +270,67 @@ async function resolveFund(
   return { cik: fund.cik, name: fund.name };
 }
 
+async function resolveFund(
+  query: string,
+  args: HeadlessPaneLoadArgs,
+  ctx: HeadlessPaneContext,
+  dependencies: ThirteenFHeadlessDependencies,
+): Promise<{ cik: string; name: string }> {
+  if (!query) throw new Error("13F holdings and filings require a fund name or CIK.");
+  return (await findThirteenFFund(query, (text, limit) => dependencies.loadBrowser("funds", text, limit, args, ctx)))!;
+}
+
+/** A word that reads as a ticker (SPY, BRK.B), not a manager's name or a CIK. */
+const TICKER_WORD = /^\$?[A-Za-z]{1,5}(?:[.-][A-Za-z])?$/;
+
+type OverlapComparison =
+  | { kind: "fund"; cik: string; name: string }
+  | { kind: "etf"; symbol: string; ticker: string; name: string };
+
+/** "IVV (also SPY, SPX), IJH": the covered funds and the aliases each answers to. */
+const coveredEtfs = (funds: MemberFundsPayload["funds"]) => funds
+  .map((fund) => fund.aliases.length ? `${fund.ticker} (also ${fund.aliases.join(", ")})` : fund.ticker).join(", ");
+
+/**
+ * What `--compare` names. A ticker-like word is an ETF when MEMB has its
+ * holdings file, else a 13F manager only by its exact name; it is never
+ * matched to a manager by a partial name (SPY is not Spyglass Capital).
+ * Anything else, a CIK or a longer name, is a 13F manager as before.
+ */
+async function resolveComparison(
+  text: string,
+  args: HeadlessPaneLoadArgs,
+  ctx: HeadlessPaneContext,
+  dependencies: Required<ThirteenFHeadlessDependencies>,
+): Promise<OverlapComparison> {
+  if (isCikQuery(text) || !TICKER_WORD.test(text)) return { kind: "fund", ...await resolveFund(text, args, ctx, dependencies) };
+  const symbol = text.replace(/^\$/, "").toUpperCase();
+  let funds: MemberFundsPayload["funds"] | null = null;
+  let failure = "";
+  try {
+    funds = await dependencies.loadEtfFunds(ctx);
+  } catch (error) {
+    if (ctx.signal.aborted) throw error;
+    failure = error instanceof Error ? error.message : String(error);
+  }
+  const etf = funds ? coveredFund(funds, symbol) : undefined;
+  if (etf) return { kind: "etf", symbol, ticker: etf.ticker, name: etf.name };
+  const manager = await findThirteenFFund(text, (query, limit) => dependencies.loadBrowser("funds", query, limit, args, ctx), { exactOnly: true });
+  if (manager) return { kind: "fund", ...manager };
+  const etfs = funds ? `${symbol} is not an ETF MEMB covers (covered: ${coveredEtfs(funds)})` : `${symbol} could not be checked against MEMB's ETFs (${failure})`;
+  throw new Error(`${etfs}, and no 13F manager is named "${text}". For a manager, use its CIK or full name.`);
+}
+
+const percentText = (value: number) => `${(value * 100).toFixed(1)}%`;
+
 export function createThirteenFHeadless(
-  dependencies: ThirteenFHeadlessDependencies = defaultDependencies,
+  overrides: ThirteenFHeadlessDependencies = defaultDependencies,
 ): HeadlessPaneDefinition<"rows"> {
+  const dependencies: Required<ThirteenFHeadlessDependencies> = { ...defaultDependencies, ...overrides };
   return {
     shape: "rows",
     freshness: { ...SEC_FILINGS, basis: "13F filings", observedKey: "filedAsOfDate" },
+    discovery: { limitations: [THIRTEENF_LIMITS] },
     argument: {
       kind: "free-text",
       placeholder: "fund, ticker, or CIK",
@@ -252,9 +338,10 @@ export function createThirteenFHeadless(
       optional: true,
     },
     options: [
-      { key: "rank", description: "Crowding order.", type: "enum", values: [{ value: "new" }, { value: "exits" }, { value: "increases" }, { value: "decreases" }], defaultValue: "new" },
-      { key: "compare", description: "Second fund name or CIK for overlap.", type: "string" },
-      { key: "offset", description: "Fund offset for ticker-holdings.", type: "integer", defaultValue: 0, minimum: 0, maximum: 100000 },
+      // No defaults on view-specific options, so a flag the view does not use can be named as ignored.
+      { key: "rank", description: "Crowding order (crowding view; new when left out).", type: "enum", values: [{ value: "new" }, { value: "exits" }, { value: "increases" }, { value: "decreases" }] },
+      { key: "compare", description: "Second fund name or CIK, or an ETF ticker MEMB covers such as SPY; implies the overlap view.", type: "string" },
+      { key: "offset", description: "Fund offset for ticker-holdings (0 when left out).", type: "integer", minimum: 0, maximum: 100000 },
       {
         key: "view",
         description: "Fund browser mode or detail tab.",
@@ -287,20 +374,80 @@ export function createThirteenFHeadless(
     async load(args, ctx) {
       const query = typeof args.argument === "string" ? args.argument.trim() : "";
       const requestedView = String(args.options.view) as HeadlessThirteenFView;
+      const compare = typeof args.options.compare === "string" ? args.options.compare.trim() : "";
+      if (compare && requestedView !== "auto" && requestedView !== "overlap") {
+        throw new Error(`--compare is for the overlap view; --view ${requestedView} does not use it. Drop --view, or use --view overlap.`);
+      }
       // A ticker's holders with their positions, not the holders' whole books.
-      const view = requestedView !== "auto" ? requestedView
-        : isCikQuery(query) ? "holdings"
-          : inferBrowserTabFromQuery(query) === "byTicker" ? "ticker-holdings"
-            : requestedView;
+      const view = compare ? "overlap"
+        : requestedView !== "auto" ? requestedView
+          : isCikQuery(query) ? "holdings"
+            : inferBrowserTabFromQuery(query) === "byTicker" ? "ticker-holdings"
+              : requestedView;
+      // A flag the view does not use is named, never dropped without a word.
+      const flagNotices = [
+        compare && requestedView === "auto" ? "--compare implies --view overlap" : "",
+        args.options.rank != null && view !== "crowding" ? "--rank orders --view crowding only; ignored here" : "",
+        args.options.offset != null && view !== "ticker-holdings" ? "--offset pages a ticker's holders only; ignored here" : "",
+        query && (view === "latest" || view === "performance") ? `--view ${view} lists every manager; "${query}" is not used` : "",
+      ].filter(Boolean);
       const limit = Number(args.options.limit);
       if (view === "overlap") {
+        if (!compare) throw new Error(`13F overlap compares two holdings: add --compare <fund name, CIK or ETF ticker>, as in fn 13F ${query || "<fund or CIK>"} --compare SPY.`);
+        if (!query) throw new Error("13F overlap needs a fund name or CIK first: fn 13F <fund or CIK> --compare <fund, CIK or ETF ticker>.");
         const fund = await resolveFund(query, args, ctx, dependencies);
-        const other = await resolveFund(String(args.options.compare ?? ""), args, ctx, dependencies);
+        const other = await resolveComparison(compare, args, ctx, dependencies);
+        if (other.kind === "etf") {
+          const [first, etf] = await Promise.all([dependencies.loadDetail(fund.cik, fund.name, args, ctx), dependencies.loadEtfHoldings(other.ticker, ctx)]);
+          const overlap = buildManagerEtfOverlap(first, etf.members);
+          const period = first.latestForm?.periodOfReport ?? null;
+          const filed = first.latestForm?.filedAsOfDate ?? null;
+          const rows = overlap?.rows ?? [];
+          const cut = cutText(rows.length, limit, "positions");
+          const missing = overlap?.missing ?? [];
+          const missingNames = missing.slice(0, 5).map((row) => `${row.ticker || row.issuer} ${weight(row.weight)}`).join(", ");
+          const leftOut = overlap ? [overlap.leftOut.options ? `${overlap.leftOut.options} option line${overlap.leftOut.options === 1 ? "" : "s"}` : "", overlap.leftOut.principal ? `${overlap.leftOut.principal} principal-amount line${overlap.leftOut.principal === 1 ? "" : "s"}` : ""].filter(Boolean) : [];
+          const etfWeight = (value: unknown, row: Record<string, unknown>) => row.etfWeight == null ? "no ticker" : value === 0 ? "not held" : weight(value);
+          return {
+            columns: [{ key: "ticker", header: "Ticker" }, { key: "issuer", header: "Issuer" }, { key: "weight", header: "13F weight", align: "right", format: weight }, { key: "etfWeight", header: `${other.symbol} weight`, align: "right", format: etfWeight }, { key: "shared", header: "Shared", align: "right", format: weight }],
+            rows: rows.slice(0, limit).map((row) => ({ ...row })),
+            errors: [
+              ...(first.warnings ?? []),
+              ...(first.latestReport?.complete === false ? [`The 13F for ${period} did not load completely; weights cover the lines that did.`] : []),
+              ...(etf.stale ? [`The ${other.ticker} holdings file is stale.`] : []),
+              ...(!overlap ? ["No share positions or ETF weights to compare."] : []),
+            ],
+            freshness: { source: "SEC EDGAR and Gloom Cloud", ...(period ? { asOf: period } : {}) },
+            metadata: {
+              view, comparedWith: "etf", firstFund: first.name, cik: first.cik, secondFund: other.symbol,
+              etf: { symbol: other.symbol, ticker: other.ticker, name: other.name, asOf: etf.asOf },
+              comparedPeriod: period, filed,
+              overlap: overlap?.overlap ?? null, activeShare: overlap?.activeShare ?? null,
+              missing: missing.map((row) => ({ ticker: row.ticker || null, issuer: row.issuer, weight: row.weight, reason: row.etfWeight == null ? "no ticker" : "not held" })),
+              missingWeight: overlap?.missingWeight ?? null,
+              leftOut: overlap?.leftOut ?? null,
+              shown: Math.min(rows.length, limit), total: rows.length, truncated: rows.length > limit,
+              notices: [
+                ...flagNotices,
+                `${other.symbol} read as an ETF: ${other.name} holdings${other.ticker !== other.symbol ? ` (${other.ticker} file)` : ""}, as fn MEMB ${other.symbol} shows`,
+                ...(overlap ? [`Overlap ${percentText(overlap.overlap)} (sum of the smaller weight per name) | Active share ${percentText(overlap.activeShare)}`] : []),
+                [
+                  period ? `Quarter compared: ${filingDayText(period)}${filed ? `, filed ${filingDayText(filed)}` : ""}` : "",
+                  `${other.symbol} holdings as of ${filingDayText(etf.asOf.slice(0, 10))}`,
+                  leftOut.length ? `13F weights leave out ${leftOut.join(" and ")}` : "",
+                ].filter(Boolean).join(" | "),
+                ...(overlap ? [missing.length ? `Not in ${other.symbol}: ${missing.length} of ${rows.length} positions, ${percentText(overlap.missingWeight)} of the 13F | ${missingNames}${missing.length > 5 ? ", ..." : ""}` : `${other.symbol} holds every position in the 13F`] : []),
+                ...(cut ? [`${cut[0]!.toUpperCase()}${cut.slice(1)}`] : []),
+              ].filter(Boolean),
+            },
+          };
+        }
         const [first, second] = await Promise.all([dependencies.loadDetail(fund.cik, fund.name, args, ctx), dependencies.loadDetail(other.cik, other.name, args, ctx)]);
         const comparedPeriod = overlapPeriod(first, second);
         const rows = buildFundOverlap(first, second);
         const cut = cutText(rows.length, limit, "positions");
-        return { columns: [{ key: "ticker", header: "Ticker" }, { key: "type", header: "Type" }, { key: "issuer", header: "Issuer" }, { key: "weight", header: "First weight", align: "right", format: weight }, { key: "comparedWeight", header: "Second weight", align: "right", format: weight }], rows: rows.slice(0, limit).map(row => ({ ...row })), errors: [...(first.warnings ?? []), ...(second.warnings ?? []), ...(!comparedPeriod ? ["No reporting quarter is loaded for both funds."] : [])], metadata: { view, firstFund: first.name, secondFund: second.name, firstPeriod: first.latestForm?.periodOfReport ?? null, secondPeriod: second.latestForm?.periodOfReport ?? null, comparedPeriod, shown: Math.min(rows.length, limit), total: rows.length, truncated: rows.length > limit, notices: [[comparedPeriod ? `Quarter compared: ${comparedPeriod}` : "", cut].filter(Boolean).join(" | ")].filter(Boolean) } };
+        const read = `${compare} read as the 13F manager ${second.name} (CIK ${second.cik})`;
+        return { columns: [{ key: "ticker", header: "Ticker" }, { key: "type", header: "Type" }, { key: "issuer", header: "Issuer" }, { key: "weight", header: "First weight", align: "right", format: weight }, { key: "comparedWeight", header: "Second weight", align: "right", format: weight }], rows: rows.slice(0, limit).map(row => ({ ...row })), errors: [...(first.warnings ?? []), ...(second.warnings ?? []), ...(!comparedPeriod ? ["No reporting quarter is loaded for both funds."] : [])], metadata: { view, comparedWith: "fund", firstFund: first.name, secondFund: second.name, firstPeriod: first.latestForm?.periodOfReport ?? null, secondPeriod: second.latestForm?.periodOfReport ?? null, comparedPeriod, shown: Math.min(rows.length, limit), total: rows.length, truncated: rows.length > limit, notices: [...flagNotices, read, [comparedPeriod ? `Quarter compared: ${comparedPeriod}` : "", cut].filter(Boolean).join(" | ")].filter(Boolean) } };
       }
       if (view === "crowding") {
         const { rows: sourceRows, ...metadata } = await loadCrowding(ctx.signal);
@@ -314,7 +461,7 @@ export function createThirteenFHeadless(
         const columns: HeadlessPaneColumn[] = [{ key: "ticker", header: "Ticker" }, { key: "issuer", header: "Issuer" }, { key: "type", header: "Type" }, { key: "holderCount", header: "Funds", align: "right" }, { key: "newCount", header: "New", align: "right" }, { key: "exitCount", header: "Exits", align: "right" }, { key: "weightChange", header: "Weight change", align: "right", format: weightPoints }, { key: "comparedFunds", header: "Compared", align: "right" }, { key: "totalValue", header: "Value (USD)", align: "right", format: money }];
         const cut = cutText(rows.length, limit, "securities");
         return { columns: focus ? [{ key: "rank", header: "Rank", align: "right" }, ...columns] : columns, rows: rows.slice(0, limit).map(row => ({ ...row })),
-          metadata: { ...metadata, view, rank, ...(ticker ? { ticker, found: rows.length > 0, rankedSecurities: ranked.length } : {}), shown: Math.min(rows.length, limit), total: rows.length, truncated: rows.length > limit, notices: [[sample, cut].filter(Boolean).join(" | "), ...(focus ? [focus.notice] : [])] },
+          metadata: { ...metadata, view, rank, ...(ticker ? { ticker, found: rows.length > 0, rankedSecurities: ranked.length } : {}), shown: Math.min(rows.length, limit), total: rows.length, truncated: rows.length > limit, notices: [...flagNotices, [sample, cut].filter(Boolean).join(" | "), ...(focus ? [focus.notice] : [])] },
           freshness: { asOf: metadata.period }, errors: metadata.warnings };
       }
       let holdings: TickerHoldings | null = null;
@@ -336,9 +483,11 @@ export function createThirteenFHeadless(
         const { rows, ...metadata } = holdings;
         const offset = Number(args.options.offset ?? 0);
         const summary = summarizeTickerHoldings({ ...metadata, offset, limit, loaded: rows });
+        const shown = rows.slice(0, limit).map(row => ({ ...row }));
         return {
-          columns: [{ key: "fund", header: "Fund" }, { key: "cik", header: "CIK" }, { key: "type", header: "Type" }, { key: "value", header: "Value (USD)", align: "right", format: money }, { key: "shares", header: "Shares", align: "right", format: shares }, { key: "weight", header: "13F weight", align: "right", format: weight }, { key: "action", header: "Action" }],
-          rows: rows.slice(0, limit).map(row => ({ ...row })),
+          columns: [{ key: "fund", header: "Fund" }, { key: "cik", header: "CIK" }, TYPE_COLUMN, { key: "value", header: "Value (USD)", align: "right", format: money }, { key: "shares", header: "Shares", align: "right", format: shares }, { key: "weight", header: "13F weight", align: "right", format: weight }, { key: "action", header: "Action" }],
+          rows: shown,
+          notes: positionNotes(shown),
           metadata: {
             ...metadata,
             view,
@@ -353,7 +502,7 @@ export function createThirteenFHeadless(
             totalValue: summary.shownValue,
             valueScope: "shown funds",
             valueBasis: "as reported at period end",
-            notices: summary.notices,
+            notices: [...flagNotices, ...summary.notices],
           },
           freshness: { asOf: metadata.period },
           errors: metadata.warnings,
@@ -370,6 +519,8 @@ export function createThirteenFHeadless(
             .slice(0, limit)
             .map((row) => ({ ...row }));
           const cut = cutText(all.length, limit, "filings");
+          const shownFilings = new Set(rows.map((row) => row.accessionNumber));
+          const restated = restatedValuesText(detail.forms.filter((form) => shownFilings.has(form.accessionNumber)));
           return {
             columns: FILING_COLUMNS,
             rows,
@@ -382,7 +533,7 @@ export function createThirteenFHeadless(
               shown: rows.length,
               total: all.length,
               truncated: all.length > limit,
-              notices: [[`CIK ${detail.cik}`, cut].filter(Boolean).join(" | ")],
+              notices: [...flagNotices, [`CIK ${detail.cik}`, cut].filter(Boolean).join(" | "), ...(restated ? [restated] : [])],
             },
           };
         }
@@ -391,7 +542,17 @@ export function createThirteenFHeadless(
           DEFAULT_HOLDING_SORT,
         );
         const previousPeriod = detail.previousForm?.periodOfReport ?? null;
+        const comparable = hasComparable13FQuarter(detail);
+        const filed = detail.latestForm?.filedAsOfDate || null;
+        const quartersBehind = quartersBehindLatest(latestPeriod);
         const cut = cutText(all.length, limit, "positions, exits included");
+        // Values, weights and Est P&L read both compared quarters' filings.
+        const reportForms = (report: typeof detail.latestReport, form: typeof detail.latestForm) =>
+          report?.filings ?? (form ? [form] : []);
+        const restated = restatedValuesText([
+          ...reportForms(detail.latestReport, detail.latestForm),
+          ...(comparable ? reportForms(detail.previousReport, detail.previousForm) : []),
+        ]);
         const rows = all
           .slice(0, limit)
           .map((row) => ({
@@ -403,22 +564,33 @@ export function createThirteenFHeadless(
           columns: HOLDING_COLUMNS,
           rows,
           ...(detail.warnings?.length ? { errors: detail.warnings } : {}),
-          // Positions as of the quarter they report; the rows carry no filing date.
-          ...(latestPeriod ? { freshness: { asOf: latestPeriod } } : {}),
+          notes: positionNotes(rows),
+          // Dated by the filing that made the positions public, with the quarter they report beside it.
+          ...(latestPeriod ? { freshness: {
+            asOf: filed ?? latestPeriod,
+            basis: `13F filing for the quarter ended ${filingDayText(latestPeriod)}`,
+          } } : {}),
           metadata: {
             view,
             cik: detail.cik,
             fund: detail.name,
             latestPeriod,
+            latestFiled: filed,
+            filingLagDays: filingLagDays(latestPeriod, filed),
+            quartersBehind,
             previousPeriod,
             shown: rows.length,
             total: all.length,
             truncated: all.length > limit,
             notices: [
-              [`CIK ${detail.cik}`, periodText(latestPeriod, hasComparable13FQuarter(detail) ? previousPeriod : null), AS_FILED_VALUE].filter(Boolean).join(" | "),
+              ...flagNotices,
+              [`CIK ${detail.cik}`, filedPeriodText(latestPeriod, filed, comparable ? previousPeriod : null)].filter(Boolean).join(" | "),
+              AS_FILED_VALUE,
+              ...(restated ? [restated] : []),
+              ...(isStaleFiling(quartersBehind) ? [staleFilingText(quartersBehind)] : []),
               ...(cut ? [`${cut[0]!.toUpperCase()}${cut.slice(1)}`] : []),
             ],
-            comparisonAvailable: hasComparable13FQuarter(detail),
+            comparisonAvailable: comparable,
             currentFilings: detail.latestReport?.filings.map((form) => form.accessionNumber) ?? [],
             previousFilings: detail.previousReport?.filings.map((form) => form.accessionNumber) ?? [],
             currentReportedValue: detail.latestReport?.complete ? detail.latestReport.tableValueTotal : null,
@@ -432,11 +604,18 @@ export function createThirteenFHeadless(
       const tab = browserTab(view === "ticker-holdings" ? requestedView : view, query);
       const result = await dependencies.loadBrowser(tab, query, limit, args, ctx);
       const more = result.hasMore || result.rows.length > limit;
+      const browserRows = sortBrowserRows(result.rows, browserSortFor(DEFAULT_BROWSER_SORT, tab)).slice(0, limit);
+      // A search finds managers that stopped filing; say which, since the Period column alone reads like any other.
+      const stale = tab === "funds"
+        ? browserRows.flatMap((row) => {
+          const quarters = quartersBehindLatest(row.periodOfReport);
+          return isStaleFiling(quarters) ? [{ name: row.name, quarters }] : [];
+        })
+        : [];
       return {
         columns: result.rows[0]?.priorReturns?.length ? [...BROWSER_COLUMNS.filter(column => !["filedAsOfDate", "tableEntryTotal"].includes(column.key)), ...result.rows[0].priorReturns.map((point, index) => ({ key: `return${index + 1}`, header: point.quarter, align: "right" as const, format: (value: unknown) => formatRawPercentMaybe(typeof value === "number" ? value : null) }))]
           : tab === "performance" ? BROWSER_COLUMNS : BROWSER_COLUMNS.filter(column => column.key !== "estQuarterReturn"),
-        rows: sortBrowserRows(result.rows, browserSortFor(DEFAULT_BROWSER_SORT, tab))
-          .slice(0, limit)
+        rows: browserRows
           .map((row) => ({ ...row, ...Object.fromEntries((row.priorReturns ?? []).map((point, index) => [`return${index + 1}`, point.value])) })),
         ...(result.warning ? { errors: [result.warning] } : {}),
         metadata: {
@@ -447,9 +626,11 @@ export function createThirteenFHeadless(
           hasMore: result.hasMore ?? false,
           shown: Math.min(result.rows.length, limit),
           truncated: more,
-          notices: more
-            ? [[`Showing the first ${Math.min(result.rows.length, limit)}`, limit < THIRTEENF_MAX_LIMIT ? `more: --limit ${THIRTEENF_MAX_LIMIT}` : ""].filter(Boolean).join(" | ")]
-            : [],
+          notices: [
+            ...flagNotices,
+            ...(more ? [[`Showing the first ${Math.min(result.rows.length, limit)}`, limit < THIRTEENF_MAX_LIMIT ? `more: --limit ${THIRTEENF_MAX_LIMIT}` : ""].filter(Boolean).join(" | ")] : []),
+            ...(stale.length ? [staleFundsText(stale)] : []),
+          ],
         },
       };
     },