kalshi-trading-bot-cli 2.1.2 → 2.1.4

package/src/commands/catalysts.ts

@@ -0,0 +1,121 @@
+/**
+ * `catalysts upcoming [--days N]` — list active Kalshi markets sorted by
+ * close_time within the next N days. Group by week so the user can scan an
+ * event-calendar view.
+ *
+ * Pure composition over /kalshi/markets — no new endpoint needed.
+ */
+import { wrapSuccess, wrapError } from './json.js';
+import type { CLIResponse } from './json.js';
+import type { ParsedArgs } from './parse-args.js';
+import { fetchUniverse } from './series.js';
+import { formatTable } from './scan-formatters.js';
+
+function truncate(s: string, max: number): string {
+  return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+
+function fmtVol(v: number | null | undefined): string {
+  if (v === null || v === undefined) return '-';
+  if (v >= 1_000_000) return `${(v / 1_000_000).toFixed(1)}M`;
+  if (v >= 1_000) return `${(v / 1_000).toFixed(1)}k`;
+  return v.toFixed(0);
+}
+
+function isoWeek(d: Date): string {
+  // Return YYYY-MM-DD of the Monday of the ISO week.
+  const tmp = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
+  const day = tmp.getUTCDay() || 7;
+  if (day !== 1) tmp.setUTCDate(tmp.getUTCDate() - (day - 1));
+  return tmp.toISOString().slice(0, 10);
+}
+
+export interface CatalystRow {
+  market_ticker: string;
+  series_prefix: string;
+  title: string;
+  category: string | null;
+  close_time: string;
+  volume_24h: number | null;
+}
+
+export interface CatalystsResult {
+  days: number;
+  weeks: Array<{ week_starting: string; markets: CatalystRow[] }>;
+  total: number;
+}
+
+export async function handleCatalysts(args: ParsedArgs): Promise<CLIResponse<CatalystsResult>> {
+  const sub = args.positionalArgs[0]?.toLowerCase() ?? 'upcoming';
+  if (sub !== 'upcoming') {
+    return wrapError('catalysts', 'UNKNOWN_SUB', `Unknown subcommand "${sub}". Try: catalysts upcoming [--days N]`);
+  }
+  const days = args.days ?? 30;
+  const now = new Date();
+  const cutoff = new Date(now.getTime() + days * 86_400_000);
+
+  try {
+    const universe = await fetchUniverse({
+      close_before: cutoff.toISOString(),
+      min_volume_24h: args.minVolume,
+      category: args.category,
+    });
+    // Filter to markets that close in the future window
+    const candidates = universe
+      .filter((m) => m.close_time && new Date(m.close_time) > now)
+      .map<CatalystRow>((m) => ({
+        market_ticker: m.market_ticker,
+        series_prefix: m.market_ticker.split('-')[0],
+        title: m.title,
+        category: m.category ?? null,
+        close_time: m.close_time as string,
+        volume_24h: m.volume_24h ?? null,
+      }))
+      .sort((a, b) => a.close_time.localeCompare(b.close_time));
+
+    // Group by ISO week of close_time
+    const buckets = new Map<string, CatalystRow[]>();
+    for (const c of candidates) {
+      const week = isoWeek(new Date(c.close_time));
+      const arr = buckets.get(week) ?? [];
+      arr.push(c);
+      buckets.set(week, arr);
+    }
+    const limit = args.limit ?? 8;
+    const weeks = Array.from(buckets.entries())
+      .sort((a, b) => a[0].localeCompare(b[0]))
+      .map(([week_starting, markets]) => ({
+        week_starting,
+        markets: markets
+          .sort((a, b) => (b.volume_24h ?? 0) - (a.volume_24h ?? 0))
+          .slice(0, limit),
+      }));
+    return wrapSuccess('catalysts', { days, weeks, total: candidates.length });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return wrapError('catalysts', 'OCTAGON_ERROR', message);
+  }
+}
+
+export function formatCatalystsHuman(result: CatalystsResult): string {
+  const lines: string[] = [];
+  lines.push(`Upcoming catalysts — next ${result.days} days, ${result.total} markets across ${result.weeks.length} weeks`);
+  lines.push('');
+  if (result.weeks.length === 0) {
+    lines.push('No markets closing in that window.');
+    return lines.join('\n');
+  }
+  for (const w of result.weeks) {
+    lines.push(`Week of ${w.week_starting} — ${w.markets.length} markets`);
+    const rows: string[][] = w.markets.map((m) => [
+      m.market_ticker,
+      truncate(m.title, 45),
+      m.close_time.slice(0, 16).replace('T', ' '),
+      fmtVol(m.volume_24h),
+      m.category ?? '-',
+    ]);
+    lines.push(formatTable(['Market', 'Title', 'Closes (UTC)', '24h Vol', 'Category'], rows));
+    lines.push('');
+  }
+  return lines.join('\n');
+}

package/src/commands/clusters.ts

@@ -0,0 +1,153 @@
+import { wrapSuccess, wrapError } from './json.js';
+import type { CLIResponse } from './json.js';
+import type { ParsedArgs } from './parse-args.js';
+import {
+  listClusters,
+  listBehavioralClusters,
+  getClusterMarkets,
+  getBehavioralClusterMarkets,
+  getClustersRankedByReturn,
+  type ClusterRow,
+  type PagedResult,
+  type SimilarMarketRow,
+  type RankedClustersResponse,
+} from '../scan/octagon-kalshi-api.js';
+import { formatTable } from './scan-formatters.js';
+
+function truncate(s: string, max: number): string {
+  return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+
+function fmtPct(v: number): string {
+  return `${(v * 100).toFixed(1)}%`;
+}
+
+export type ClustersResult =
+  | { kind: 'list'; behavioral: boolean; data: ClusterRow[] }
+  | { kind: 'members'; behavioral: boolean; cluster_id: number; markets: PagedResult<SimilarMarketRow> }
+  | { kind: 'ranked'; data: RankedClustersResponse };
+
+export async function handleClusters(args: ParsedArgs): Promise<CLIResponse<ClustersResult>> {
+  try {
+    if (args.ranked) {
+      const data = await getClustersRankedByReturn({
+        timeframe: args.timeframe,
+        min_return: args.minReturn,
+        top_n_per_cluster: args.topK,
+        kind: args.behavioral ? 'behavioral' : 'thematic',
+        max_clusters: args.limit,
+      });
+      return wrapSuccess('clusters', { kind: 'ranked', data });
+    }
+
+    const positional = args.positionalArgs[0];
+    if (positional !== undefined && /^\d+$/.test(positional)) {
+      const clusterId = Number(positional);
+      const markets = args.behavioral
+        ? await getBehavioralClusterMarkets(clusterId, { limit: args.limit })
+        : await getClusterMarkets(clusterId, { limit: args.limit });
+      return wrapSuccess('clusters', { kind: 'members', behavioral: args.behavioral, cluster_id: clusterId, markets });
+    }
+
+    const params = {
+      limit: args.limit,
+      sample_titles: 3,
+      label_contains: args.labelContains,
+    };
+    const data = args.behavioral
+      ? await listBehavioralClusters(params)
+      : await listClusters(params);
+    return wrapSuccess('clusters', { kind: 'list', behavioral: args.behavioral, data: data.data });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return wrapError('clusters', 'OCTAGON_ERROR', message);
+  }
+}
+
+export function formatClustersHuman(result: ClustersResult): string {
+  if (result.kind === 'list') return formatClusterList(result.data, result.behavioral);
+  if (result.kind === 'members') return formatClusterMembers(result.cluster_id, result.markets, result.behavioral);
+  return formatRankedClusters(result.data);
+}
+
+function formatClusterList(clusters: ClusterRow[], behavioral: boolean): string {
+  const lines: string[] = [];
+  const kindLabel = behavioral ? 'Behavioral' : 'Thematic';
+  lines.push(`${kindLabel} clusters — ${clusters.length} result(s)`);
+  lines.push('');
+
+  if (clusters.length === 0) {
+    lines.push('No clusters found.');
+    return lines.join('\n');
+  }
+
+  const headers = behavioral
+    ? ['ID', 'Label', 'Size', 'Mean Ret', 'Vol', 'Sample']
+    : ['ID', 'Label', 'Size', 'Sample'];
+
+  const rows: string[][] = clusters.map((c) => {
+    const sample = truncate(c.sample_titles[0] ?? '-', 50);
+    if (behavioral) {
+      return [
+        String(c.cluster_id),
+        truncate(c.label, 30),
+        String(c.size),
+        c.mean_daily_return != null ? fmtPct(c.mean_daily_return) : '-',
+        c.daily_volatility != null ? fmtPct(c.daily_volatility) : '-',
+        sample,
+      ];
+    }
+    return [String(c.cluster_id), truncate(c.label, 30), String(c.size), sample];
+  });
+
+  lines.push(formatTable(headers, rows));
+  lines.push('');
+  lines.push(`Use "clusters <id>${behavioral ? ' --behavioral' : ''}" to list members.`);
+  return lines.join('\n');
+}
+
+function formatClusterMembers(clusterId: number, page: PagedResult<SimilarMarketRow>, behavioral: boolean): string {
+  const lines: string[] = [];
+  const kindLabel = behavioral ? 'behavioral' : 'thematic';
+  lines.push(`Markets in ${kindLabel} cluster ${clusterId} — ${page.data.length} shown${page.has_more ? ' (more available)' : ''}`);
+  lines.push('');
+
+  if (page.data.length === 0) {
+    lines.push('No markets in this cluster.');
+    return lines.join('\n');
+  }
+
+  const rows: string[][] = page.data.map((m) => [
+    m.market_ticker,
+    truncate(m.title, 45),
+    m.distance != null ? m.distance.toFixed(3) : '-',
+    m.category ?? '-',
+  ]);
+
+  lines.push(formatTable(['Ticker', 'Title', 'Distance', 'Category'], rows));
+  return lines.join('\n');
+}
+
+function formatRankedClusters(data: RankedClustersResponse): string {
+  const lines: string[] = [];
+  lines.push(`Clusters ranked by ${data.timeframe} return (${data.kind}, top ${data.top_n_per_cluster} per cluster, min return ${(data.min_return * 100).toFixed(1)}%)`);
+  lines.push('');
+
+  if (data.data.length === 0) {
+    lines.push('No clusters meet the threshold.');
+    return lines.join('\n');
+  }
+
+  const rows: string[][] = data.data.map((c) => [
+    String(c.cluster_id),
+    truncate(c.label, 30),
+    String(c.size),
+    fmtPct(c.summary.total_return),
+    c.summary.sharpe != null ? c.summary.sharpe.toFixed(2) : '-',
+    fmtPct(c.summary.max_drawdown),
+    fmtPct(c.summary.win_rate),
+  ]);
+
+  lines.push(formatTable(['ID', 'Label', 'Size', 'Total Ret', 'Sharpe', 'Max DD', 'Win%'], rows));
+  return lines.join('\n');
+}

package/src/commands/correlate.ts

@@ -0,0 +1,112 @@
+import { wrapSuccess, wrapError } from './json.js';
+import type { CLIResponse } from './json.js';
+import type { ParsedArgs } from './parse-args.js';
+import { getCorrelations, type CorrelationResponseWithSides } from '../scan/octagon-kalshi-api.js';
+import { formatTable } from './scan-formatters.js';
+
+function shortTicker(t: string, max = 18): string {
+  return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+}
+
+function collectTickers(args: ParsedArgs): string[] {
+  const set = new Set<string>();
+  for (const p of args.positionalArgs) {
+    const upper = p.toUpperCase();
+    if (upper) set.add(upper);
+  }
+  if (args.tickers) {
+    for (const t of args.tickers.split(',')) {
+      const upper = t.trim().toUpperCase();
+      if (upper) set.add(upper);
+    }
+  }
+  return Array.from(set);
+}
+
+export async function handleCorrelate(args: ParsedArgs): Promise<CLIResponse<CorrelationResponseWithSides>> {
+  const tickers = collectTickers(args);
+  if (tickers.length < 2) {
+    return wrapError(
+      'correlate',
+      'TOO_FEW_TICKERS',
+      'Usage: correlate <ticker1> <ticker2> [...] [--window-days N] [--sides yes,no,yes] [--cells]',
+    );
+  }
+  if (tickers.length > 100) {
+    return wrapError('correlate', 'TOO_MANY_TICKERS', 'At most 100 tickers allowed.');
+  }
+
+  // --sides yes,no,yes — must match ticker count (server enforces this too)
+  let sides: ('yes' | 'no')[] | undefined;
+  if (args.sides) {
+    sides = args.sides.split(',').map((s) => (s.trim().toLowerCase() === 'no' ? 'no' : 'yes'));
+    if (sides.length !== tickers.length) {
+      return wrapError('correlate', 'SIDES_MISMATCH',
+        `--sides has ${sides.length} entries but ${tickers.length} tickers were supplied.`);
+    }
+  }
+
+  try {
+    const data = await getCorrelations({
+      market_tickers: tickers,
+      sides,
+      include_cell_detail: args.cells || undefined,
+      window_days: args.windowDays,
+      interval: args.correlationInterval,
+    });
+    return wrapSuccess('correlate', data);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return wrapError('correlate', 'OCTAGON_ERROR', message);
+  }
+}
+
+export function formatCorrelationHuman(data: CorrelationResponseWithSides): string {
+  const lines: string[] = [];
+  const sidesLabel = data.sides ? ` (sides: ${data.sides.join(',')})` : '';
+  lines.push(`Correlation matrix — ${data.tickers.length} markets${sidesLabel}, ${data.window_days}d window, interval ${data.interval}`);
+  if (data.missing.length > 0) {
+    lines.push(`  Dropped (no candle data): ${data.missing.join(', ')}`);
+  }
+  lines.push('');
+
+  if (data.tickers.length === 0) {
+    lines.push('No matrix available — all tickers were missing candle data.');
+    return lines.join('\n');
+  }
+
+  // Matrix table — header row of short tickers, body of correlation values.
+  const headerRow: string[][] = [['', ...data.tickers.map((t) => shortTicker(t, 14))]];
+  const bodyRows: string[][] = data.matrix.map((row, i) => [
+    shortTicker(data.tickers[i] ?? '?', 14),
+    ...row.map((v) => (v == null ? '-' : v.toFixed(2))),
+  ]);
+  lines.push(formatTable(headerRow[0], bodyRows));
+
+  if (data.ranked_pairs.length > 0) {
+    lines.push('');
+    lines.push('Most-uncorrelated pairs (ascending):');
+    const topN = data.ranked_pairs.slice(0, 10);
+    const rows: string[][] = topN.map((p) => [
+      shortTicker(p.ticker_a, 22),
+      shortTicker(p.ticker_b, 22),
+      p.correlation.toFixed(3),
+    ]);
+    lines.push(formatTable(['Ticker A', 'Ticker B', 'Corr'], rows));
+  }
+
+  if (data.cells_detail && data.cells_detail.length > 0) {
+    lines.push('');
+    lines.push('Cell detail:');
+    const rows: string[][] = data.cells_detail.map((c) => [
+      shortTicker(c.ticker_a, 20),
+      shortTicker(c.ticker_b, 20),
+      c.correlation == null ? '-' : c.correlation.toFixed(3),
+      String(c.overlap_count),
+      c.reason,
+    ]);
+    lines.push(formatTable(['Ticker A', 'Ticker B', 'Corr', 'Overlap', 'Reason'], rows));
+  }
+
+  return lines.join('\n');
+}

package/src/commands/dispatch.ts

@@ -26,6 +26,17 @@ import { scanEdges, formatEdgeScanHuman } from './search-edge.js';
 import type { KalshiBalanceResponse } from './formatters.js';
 import { ExitCode, exitCodeFromError } from '../utils/errors.js';
 import { trackEvent } from '../utils/telemetry.js';
+import { handleSimilar, formatSimilarHuman } from './similar.js';
+import { handleClusters, formatClustersHuman } from './clusters.js';
+import { handlePeers, formatPeersHuman } from './peers.js';
+import { handleCorrelate, formatCorrelationHuman } from './correlate.js';
+import { handleBasket, formatBasketHuman } from './basket.js';
+import { searchKalshiMarkets, getMarketsWithEdge } from '../scan/octagon-kalshi-api.js';
+import { formatMarketSearchHuman, formatMarketsWithEdgeHuman } from './search-remote.js';
+import { handleEvents, formatEventsHuman } from './events.js';
+import { handleSeries, formatSeriesHuman } from './series.js';
+import { handleEditorialThemes, formatEditorialThemesHuman } from './editorial-themes.js';
+import { handleCatalysts, formatCatalystsHuman } from './catalysts.js';
 
 // ─── Alias resolution ────────────────────────────────────────────────────────
 // Maps legacy CLI subcommands to canonical commands with mode/subview context
@@ -45,19 +56,49 @@ function resolveAlias(subcommand: Subcommand, positionalArgs: string[]): Resolve
     case 'status':
       return { canonical: 'portfolio', subview: 'status' };
 
-    // themes → search themes
-    case 'themes':
-      return { canonical: 'search', subview: 'themes' };
+    // `themes` is now the editorial-themes registry (curated narrative buckets).
+    // Legacy "kalshi search themes" (Kalshi category labels) is still reachable
+    // via `search themes`.
+
+    // basket sub-routing (build/backtest/size/candles) — exposed for telemetry granularity
+    case 'basket': {
+      const sub = positionalArgs[0]?.toLowerCase();
+      if (sub === 'build' || sub === 'backtest' || sub === 'size' || sub === 'candles') {
+        return { canonical: 'basket', subview: sub };
+      }
+      return { canonical: 'basket' };
+    }
 
     default:
       return { canonical: subcommand };
   }
 }
 
+function modeFlagsFor(canonical: Subcommand, args: ParsedArgs): Record<string, string | boolean> {
+  switch (canonical) {
+    case 'clusters':
+      return { behavioral: args.behavioral, ranked: args.ranked };
+    case 'peers':
+      return { behavioral: args.behavioral, show_cluster: args.showCluster };
+    case 'similar':
+      return { anchor: args.ticker ? 'ticker' : args.query ? 'query' : 'positional' };
+    case 'basket':
+      return { kelly_sizing: args.bankroll !== undefined };
+    case 'search':
+      return { remote: !!process.env.OCTAGON_API_KEY };
+    default:
+      return {};
+  }
+}
+
 export async function dispatch(args: ParsedArgs): Promise<void> {
   const { subcommand, json } = args;
   const resolved = resolveAlias(subcommand, args.positionalArgs);
-  trackEvent('cli_command', { command: resolved.canonical, subview: resolved.subview ?? '' });
+  trackEvent('cli_command', {
+    command: resolved.canonical,
+    subview: resolved.subview ?? '',
+    ...modeFlagsFor(resolved.canonical, args),
+  });
 
   try {
     // ─── reject invalid flags early (for all commands) ───────────────
@@ -87,8 +128,26 @@ export async function dispatch(args: ParsedArgs): Promise<void> {
         return;
       }
       if (sub === 'edge') {
-        const db = (await import('../db/index.js')).getDb();
         const minEdgePp = (args.minEdge ?? 0.05) * 100;
+        if (process.env.OCTAGON_API_KEY) {
+          // edge_pp_min is asymmetric (only filters lower bound). Skip when
+          // user passes --min-edge 0 so they see the full distribution.
+          const data = await getMarketsWithEdge({
+            category: args.category,
+            ...(minEdgePp > 0 ? { edge_pp_min: minEdgePp } : {}),
+            sort_by: (args.sortBy as 'edge_pp' | 'expected_return' | 'total_volume' | 'model_probability' | undefined) ?? 'edge_pp',
+            limit: args.limit ?? 20,
+          });
+          if (json) {
+            console.log(JSON.stringify(wrapSuccess('search', data)));
+          } else {
+            console.log(formatMarketsWithEdgeHuman(data, minEdgePp));
+          }
+          process.exit(ExitCode.SUCCESS);
+          return;
+        }
+        // Local fallback: scan cached Octagon reports in SQLite
+        const db = (await import('../db/index.js')).getDb();
         const result = scanEdges(db, { minEdgePp, limit: args.limit, category: args.category });
         if (json) {
           console.log(JSON.stringify(wrapSuccess('search', result)));
@@ -109,14 +168,60 @@ export async function dispatch(args: ParsedArgs): Promise<void> {
         process.exit(resp.ok ? ExitCode.SUCCESS : ExitCode.USER_ERROR);
         return;
       }
-      // General search: query the local event index
+      const query = args.positionalArgs.join(' ');
+
+      // Octagon-powered server-side search: broader universe, full-text + structured filters.
+      if (process.env.OCTAGON_API_KEY) {
+        // --aggregate-by series → route to series rollup
+        if (args.aggregateBy === 'series') {
+          const { handleSeries, formatSeriesHuman } = await import('./series.js');
+          const seriesArgs = { ...args, positionalArgs: query ? ['search', query] : ['list'] };
+          const resp = await handleSeries(seriesArgs);
+          if (json) {
+            console.log(JSON.stringify(resp));
+          } else if (resp.ok) {
+            console.log(formatSeriesHuman(resp.data));
+          } else {
+            console.error(resp.error?.message ?? 'series rollup failed');
+          }
+          process.exit(resp.ok ? ExitCode.SUCCESS : ExitCode.USER_ERROR);
+          return;
+        }
+        // sort_by is now server-side (true top-N across the whole universe);
+        // series_prefix lets us tree-browse (KXBTC matches all Bitcoin series).
+        const serverSortBy = (args.sortBy === 'volume_24h' || args.sortBy === 'close_time' || args.sortBy === 'last_price')
+          ? args.sortBy
+          : undefined;
+        const page = await searchKalshiMarkets({
+          q: query,
+          category: args.category,
+          series_ticker: args.seriesTicker,
+          series_prefix: args.seriesPrefix,
+          min_volume_24h: args.minVolume,
+          close_before: args.closeBefore,
+          sort_by: serverSortBy,
+          limit: args.limit ?? 30,
+        });
+        // --active-only is defensive — the live universe is active by default.
+        const rows = args.activeOnly
+          ? page.data.filter((m) => m.status === 'active' || m.status === 'open')
+          : page.data;
+        const filteredPage = { ...page, data: rows };
+        if (json) {
+          console.log(JSON.stringify(wrapSuccess('search', filteredPage)));
+        } else {
+          console.log(formatMarketSearchHuman(query, filteredPage));
+        }
+        return;
+      }
+
+      // Local fallback: query the pre-built event index.
       if (args.refresh) {
         await forceRefreshIndex();
       } else {
         await ensureIndex();
       }
       const db = (await import('../db/index.js')).getDb();
-      const query = args.positionalArgs.join(' ');
       const results = searchEventIndex(db, query, 30);
       if (json) {
         console.log(JSON.stringify(wrapSuccess('search', { events: results })));
@@ -228,6 +333,132 @@ export async function dispatch(args: ParsedArgs): Promise<void> {
       return;
     }
 
+    // ─── similar (Octagon semantic search) ─────────────────────────────
+    if (resolved.canonical === 'similar') {
+      const resp = await handleSimilar(args);
+      if (json) {
+        console.log(JSON.stringify(resp));
+      } else if (resp.ok) {
+        console.log(formatSimilarHuman(resp.data));
+      } else {
+        console.error(resp.error?.message ?? 'similar failed');
+      }
+      process.exit(resp.ok ? ExitCode.SUCCESS : ExitCode.USER_ERROR);
+      return;
+    }
+
+    // ─── clusters (Octagon thematic & behavioral) ──────────────────────
+    if (resolved.canonical === 'clusters') {
+      const resp = await handleClusters(args);
+      if (json) {
+        console.log(JSON.stringify(resp));
+      } else if (resp.ok) {
+        console.log(formatClustersHuman(resp.data));
+      } else {
+        console.error(resp.error?.message ?? 'clusters failed');
+      }
+      process.exit(resp.ok ? ExitCode.SUCCESS : ExitCode.USER_ERROR);
+      return;
+    }
+
+    // ─── peers (Octagon cluster peers) ─────────────────────────────────
+    if (resolved.canonical === 'peers') {
+      const resp = await handlePeers(args);
+      if (json) {
+        console.log(JSON.stringify(resp));
+      } else if (resp.ok) {
+        console.log(formatPeersHuman(resp.data));
+      } else {
+        console.error(resp.error?.message ?? 'peers failed');
+      }
+      process.exit(resp.ok ? ExitCode.SUCCESS : ExitCode.USER_ERROR);
+      return;
+    }
+
+    // ─── correlate (Octagon correlation matrix) ────────────────────────
+    if (resolved.canonical === 'correlate') {
+      const resp = await handleCorrelate(args);
+      if (json) {
+        console.log(JSON.stringify(resp));
+      } else if (resp.ok) {
+        console.log(formatCorrelationHuman(resp.data));
+      } else {
+        console.error(resp.error?.message ?? 'correlate failed');
+      }
+      process.exit(resp.ok ? ExitCode.SUCCESS : ExitCode.USER_ERROR);
+      return;
+    }
+
+    // ─── catalysts (upcoming market closes grouped by week) ────────────
+    if (resolved.canonical === 'catalysts') {
+      const resp = await handleCatalysts(args);
+      if (json) {
+        console.log(JSON.stringify(resp));
+      } else if (resp.ok) {
+        console.log(formatCatalystsHuman(resp.data));
+      } else {
+        console.error(resp.error?.message ?? 'catalysts failed');
+      }
+      process.exit(resp.ok ? ExitCode.SUCCESS : ExitCode.USER_ERROR);
+      return;
+    }
+
+    // ─── themes (editorial narrative registry) ─────────────────────────
+    if (resolved.canonical === 'themes') {
+      const resp = await handleEditorialThemes(args);
+      if (json) {
+        console.log(JSON.stringify(resp));
+      } else if (resp.ok) {
+        console.log(formatEditorialThemesHuman(resp.data));
+      } else {
+        console.error(resp.error?.message ?? 'themes failed');
+      }
+      process.exit(resp.ok ? ExitCode.SUCCESS : ExitCode.USER_ERROR);
+      return;
+    }
+
+    // ─── series (Kalshi series rollup) ─────────────────────────────────
+    if (resolved.canonical === 'series') {
+      const resp = await handleSeries(args);
+      if (json) {
+        console.log(JSON.stringify(resp));
+      } else if (resp.ok) {
+        console.log(formatSeriesHuman(resp.data));
+      } else {
+        console.error(resp.error?.message ?? 'series failed');
+      }
+      process.exit(resp.ok ? ExitCode.SUCCESS : ExitCode.USER_ERROR);
+      return;
+    }
+
+    // ─── events (Octagon events list / detail) ─────────────────────────
+    if (resolved.canonical === 'events') {
+      const resp = await handleEvents(args);
+      if (json) {
+        console.log(JSON.stringify(resp));
+      } else if (resp.ok) {
+        console.log(formatEventsHuman(resp.data));
+      } else {
+        console.error(resp.error?.message ?? 'events failed');
+      }
+      process.exit(resp.ok ? ExitCode.SUCCESS : ExitCode.USER_ERROR);
+      return;
+    }
+
+    // ─── basket (build, backtest, size, candles) ───────────────────────
+    if (resolved.canonical === 'basket') {
+      const resp = await handleBasket(args);
+      if (json) {
+        console.log(JSON.stringify(resp));
+      } else if (resp.ok) {
+        console.log(formatBasketHuman(resp.data));
+      } else {
+        console.error(resp.error?.message ?? 'basket failed');
+      }
+      process.exit(resp.ok ? ExitCode.SUCCESS : ExitCode.USER_ERROR);
+      return;
+    }
+
     // ─── watch ─────────────────────────────────────────────────────────
     if (resolved.canonical === 'watch') {
       // Force index rebuild before watching if --refresh is set