kalshi-trading-bot-cli 2.1.2 → 2.1.4

package/src/commands/help.ts

@@ -10,20 +10,32 @@ function prefix(ctx: HelpContext): string {
 function buildTopics(ctx: HelpContext): Record<string, string> {
   const p = prefix(ctx);
   return {
-    search: `**${p}search** — Discovery
+    search: `**${p}search** — Discovery (Octagon-powered when OCTAGON_API_KEY is set)
 
-${p}search [theme|ticker|query]  Search events by theme, ticker, or free-text
+${p}search [theme|ticker|query]  Full-text market search (server-side when key is set, else local index)
 ${p}search themes                List all available themes and subcategories
-${p}search edge                  Scan all markets by Octagon model edge
+${p}search edge                  Edge ranking from latest Octagon run (server-side) or local cache
 ${p}search edge --min-edge 30    Markets with ≥30pp edge
 ${p}search edge --limit 50       Top 50 results
 ${p}search edge --category crypto Filter by category
+${p}search edge --sort-by total_volume  Sort: edge_pp | expected_return | total_volume | model_probability
+
+Search flags (server-side path):
+  --category <name>     Filter by category
+  --series <ticker>     Filter to a series
+  --min-volume <n>      Floor on 24h volume
+  --close-before <iso>  Only markets closing before
+  --limit <n>           Page size (default 30)
+  --sort-by <key>       volume_24h | close_time | last_price (client-side sort)
+  --aggregate-by series Roll up results by series (calls series rollup)
+  --active-only         Drop non-active markets (defensive; the live universe is active by default)
 
 Examples:
   ${p}search crypto
-  ${p}search crypto:btc
-  ${p}search "bitcoin price"
-  ${p}search edge --min-edge 30 --category crypto`,
+  ${p}search "bitcoin price" --min-volume 10000
+  ${p}search edge --min-edge 30 --category crypto
+
+Tip: ${p}similar gives semantic match (catches "Bitcoin pierce six figures" ↔ "BTC > $100k").`,
 
     portfolio: `**${p}portfolio** — Account state
 
@@ -125,6 +137,219 @@ ${p}init                       Launch the TUI with the setup wizard open
 
 ${p}help                       Show all commands
 ${p}help <command>             Show detailed help for a command`,
+
+    similar: `**${p}similar** — Semantic market search (Octagon-powered)
+
+${p}similar <ticker>                  Markets near this ticker by embedding distance
+${p}similar -q "free-text query"      Markets matching free-text intent (server-side embed)
+${p}similar <ticker> --top-k 25       Return top-25 nearest neighbors
+${p}similar -q "..." --category crypto --min-volume 10000 --close-before 2026-08-19T00:00:00Z
+
+Flags:
+  --top-k <n>             Number of neighbors (default 25, max 100)
+  --category <name>       Restrict to a Kalshi category
+  --min-volume <n>        Floor on 24h volume
+  --close-before <iso>    Only markets closing before this timestamp
+  --json                  JSON output
+
+Catches matches keyword search misses — "Will Bitcoin pierce six figures" ↔ "BTC over $100k".`,
+
+    clusters: `**${p}clusters** — Browse Octagon clusters (thematic + behavioral)
+
+${p}clusters                              List thematic clusters with sample titles
+${p}clusters --label fed                  Filter by label substring
+${p}clusters <id>                         Show markets in cluster
+${p}clusters --behavioral                 List behavioral clusters (mean return + vol)
+${p}clusters <id> --behavioral            Members of a behavioral cluster
+${p}clusters --ranked                     Rank clusters by historical basket return
+${p}clusters --ranked --timeframe 1y --min-return 0.20 --top-k 5
+
+Flags:
+  --behavioral            Use behavioral clustering (30-day return vectors)
+  --label <substring>     Case-insensitive label filter
+  --ranked                Score clusters by equal-weight basket return
+  --timeframe <1w|1m|3m|6m|1y>   Window for --ranked (default 1y)
+  --min-return <n>        Minimum total_return to include (e.g. 0.20)
+  --top-k <n>             Basket size per cluster for --ranked (default 5)
+  --limit <n>             Max clusters to evaluate
+  --json                  JSON output`,
+
+    peers: `**${p}peers** — Find markets in the same cluster as a ticker
+
+${p}peers <ticker>                        Thematic cluster peers (default)
+${p}peers <ticker> --behavioral           Behavioral cluster peers
+${p}peers <ticker> --limit 50             Up to 50 peers (excluding anchor)
+${p}peers <ticker> --show-cluster         Just show which clusters this ticker belongs to
+
+Flags:
+  --behavioral            Use behavioral clusters instead of thematic
+  --limit <n>             Number of peers to return (default 50)
+  --show-cluster          Print cluster membership only (no peer list)
+  --json                  JSON output`,
+
+    correlate: `**${p}correlate** — Pairwise correlation matrix over close-price candles
+
+${p}correlate <ticker1> <ticker2> [...]   Pearson correlation across 2-100 tickers
+${p}correlate --tickers KX-A,KX-B,KX-C    Same, comma-separated
+${p}correlate KX-A KX-B --window-days 90  90-day lookback
+${p}correlate KX-A KX-B --sides yes,no    Side-aware: corr(YES_A, NO_B) flips sign
+${p}correlate KX-A KX-B --cells           Per-cell detail (overlap_count + reason)
+
+Flags:
+  --window-days <n>             Lookback (1-730, default 30; auto interval picks 1d if >=90)
+  --correlation-interval <1h|1d>  Override bin size
+  --tickers <csv>               Alternative to positional args
+  --sides yes,no,yes            Per-ticker side (same length as tickers); default all yes
+  --cells                       Include per-cell detail (overlap_count, reason)
+  --json                        JSON output (matrix + ranked_pairs + cells_detail)
+
+Output ranks pairs ascending by correlation — most-uncorrelated first.`,
+
+    events: `**${p}events** — Octagon event rollups (event ↔ outcome ladder)
+
+${p}events                              List events sorted by total_volume
+${p}events --category Politics          Filter by series_category
+${p}events --min-volume 10000           Volume floor
+${p}events --limit 25                   Page size (default 50)
+${p}events KXFEDCHAIRNOM-29             Drill into one event: outcome probabilities + per-contract edge
+
+Flags:
+  --category <name>     Filter by series_category (case-insensitive substring)
+  --min-volume <n>      Floor on total_volume
+  --limit <n>           Page size (default 50)
+  --json                JSON envelope output
+
+Each event is a multi-market Kalshi question (e.g. "Who will Trump nominate as Fed Chair?")
+with one binary sub-market per outcome (Kevin Warsh, Judy Shelton, ...).
+Octagon supplies a model_probability per outcome so you can rank contracts by edge.`,
+
+    series: `**${p}series** — Series-level rollups over the Kalshi universe
+
+${p}series                          List series with 24h vol, market count, dominant category
+${p}series list --min-volume 10000  Liquidity filter
+${p}series list --category Crypto   Filter by category
+${p}series KXBTCD                   Drill in: all sub-markets sorted by volume
+${p}series search "bitcoin"         Keyword search → rolled up by series
+${p}series candles KXBTCD --timeframe 3m   Series NAV = equal-weight basket of top sub-markets
+${p}series events KXIPO              List events in a series (e.g. KXIPO → KXIPO-26)
+
+Flags:
+  --min-volume <n>       Floor on 24h volume per series
+  --category <name>      Filter by category
+  --limit <n>            Page size (default 50)
+  --timeframe <1w|1m|3m|6m|1y>  Candle window (default 1y; for "series candles")
+  --top-k <n>            Sub-markets to include in series NAV basket (default 20)
+  --series <prefix>      Filter list by series-ticker prefix (e.g. KXBTC)
+  --json                 JSON output
+
+A series is the Kalshi grouping above individual markets — KXBTCD is the BTC
+strike ladder, with hundreds of sub-markets like KXBTCD-26DEC31-T100000.
+Series list is now a single server-side call (was 25 paginated calls).`,
+
+    catalysts: `**${p}catalysts** — Upcoming Kalshi market closes grouped by week
+
+${p}catalysts upcoming                       Next 30 days
+${p}catalysts upcoming --days 7              Next week
+${p}catalysts upcoming --days 14 --min-volume 5000 --category Politics
+${p}catalysts upcoming --limit 10            Up to 10 markets per week shown
+
+Flags:
+  --days <n>           Lookback window (default 30)
+  --min-volume <n>     Floor on 24h volume
+  --category <name>    Filter by category
+  --limit <n>          Top-N markets per week (default 8)
+  --json               JSON output
+
+Use for catalyst-calendar planning: see which weeks have major Kalshi
+resolutions cluster up so you can position before catalyst risk.`,
+
+    themes: `**${p}themes** — Editorial narrative registry (curated theme buckets)
+
+${p}themes                                List registered editorial themes
+${p}themes import                         Seed from data/themes_seo.json (25 starter themes)
+${p}themes import <path>                  Import from a custom JSON file
+${p}themes export <path>                  Export current registry
+${p}themes show "Iran Escalation"         Drill into one theme
+${p}themes create "My Theme" --tickers KXA,KXB --label "..." [--min-volume N]
+${p}themes delete "My Theme"
+${p}themes add-series "My Theme" KXBTCD,KXETHD
+${p}themes remove-series "My Theme" KXBTCD
+${p}themes set-search-volume "My Theme" 100000
+${p}themes report                         Dashboard: 25-theme grid with SEO + liquidity
+${p}themes audit                          Flag dead themes (high SEO + zero volume)
+${p}themes overlap                        Cross-theme dedupe report
+
+Editorial themes are narrative buckets you curate (e.g. "AI Race Milestones",
+"Iran Escalation") — distinct from Octagon's ML clusters. Each theme maps to a
+list of Kalshi series and an optional monthly search-volume estimate.
+
+Flags:
+  --label <desc>        Set description on create
+  --min-volume <n>      Set search_volume on create (poorly named — improve later)
+  --tickers <csv>       Comma-separated series on create
+  --json                JSON output
+
+Legacy: ${p}search themes still lists Kalshi category labels (the pre-registry view).`,
+
+    basket: `**${p}basket** — Build, backtest, and size diversified baskets
+
+${p}basket build [universe filters] [-n N] [--max-per-cluster M] [--max-corr X] [--bankroll $ --kelly K --probs ...]
+${p}basket backtest --tickers KX-A,KX-B --weights 0.6,0.4 --timeframe 1y
+${p}basket candles  --tickers KX-A,KX-B --timeframe 6m
+${p}basket size     --bankroll 1000 --kelly 0.25 --probs KX-A:0.62,KX-B:0.55 [--side yes|no]
+
+Validate flags:
+  --tickers KX-A,KX-B           Validate explicit tickers (equal-stake split)
+  --probs KX-A:yes:170,KX-B:no:160  Per-leg ticker:side:stake
+  --theme <name>                Resolve from editorial registry
+  --bankroll <usd>              Used to compute max_leg_pct + warnings
+  --window-days <n>             Correlation lookback (default 30)
+  --max-corr <-1..1>            Soft threshold for correlation warning
+
+Build flags (universe + diversification):
+  --category <name>             Restrict candidate pool by category
+  --series <ticker>             Restrict to a series
+  --min-volume <n>              Volume floor for candidates
+  --close-before <iso>          Only markets closing before
+  --label <csv>                 Restrict cluster labels (substring match, comma-separated)
+  -q "<text>"                   Anchor candidate pool by free-text intent (semantic)
+  --ticker <ticker>             Anchor candidate pool by ticker (semantic)
+  --tickers KX-A,KX-B           Explicit candidate pool (universe.market_tickers)
+  --theme <name>                Resolve theme registry → explicit candidate pool
+  --auto-probs                  Auto-fetch model probabilities (markets/edge)
+                                and use Kelly sizing
+  -n <n>                        Number of legs (1-20)
+  --max-per-cluster <n>         Cap legs per thematic cluster
+  --max-corr <x>                Pairwise correlation cap (-1 to 1)
+  --limit <n>                   Candidate pool size (2-200)
+  --window-days <n>             Correlation window (7-365)
+
+Sizing flags (build & size):
+  --bankroll <usd>              Required for Kelly sizing
+  --kelly <fraction>            Kelly multiplier 0-1 (default 0.25)
+  --probs KX-A:0.62,KX-B:0.55   Model probabilities per ticker (manual)
+  --auto-probs --tickers KX-A,KX-B   Auto-fetch via POST /markets/edge
+  --auto-probs --theme <name>   Resolve theme + auto-fetch probabilities
+  --side <yes|no>               Default leg side for "basket size" (default yes)
+
+Backtest/candles flags:
+  --tickers <csv>               Tickers (required if --theme is absent)
+  --theme <name>                Resolve from editorial registry (top market per series)
+  --weights <csv>               Optional weights, same length as tickers
+  --timeframe <1w|1m|3m|6m|1y>  Window/bin size
+
+Common:
+  --json                        JSON output
+
+Recipes:
+  ${p}basket build --category crypto --min-volume 10000 -n 8 --max-per-cluster 2 --max-corr 0.6
+  ${p}basket build --label fed,cpi,fomc,gdp,jobs -n 5 --max-per-cluster 1 --max-corr 0.4
+  ${p}basket build --tickers KX-A,KX-B,KX-C -n 2 --max-corr 0.5   # explicit candidate pool
+  ${p}basket build --theme "Iran Escalation" -n 3 --max-per-cluster 1 --auto-probs --bankroll 1000
+  ${p}basket backtest --tickers KX-A,KX-B,KX-C --weights 0.4,0.4,0.2 --timeframe 1y
+  ${p}basket size --auto-probs --theme "Iran Escalation" --bankroll 1000 --kelly 0.25
+  ${p}basket validate --theme "Iran Escalation" --bankroll 1000      # sanity-check before placing
+  ${p}basket validate --tickers KX-A,KX-B --bankroll 1000 --max-corr 0.5`,
   };
 }
 
@@ -139,14 +364,44 @@ Quick start:
   kalshi watch --theme crypto   Continuous scan across a theme
 
 Discovery:
-  search [theme|ticker|query]   Find markets by keyword or theme
-  search --refresh <query>      Force index rebuild then search
-  search themes                 List all themes and subcategories
-  search edge [--min-edge N]    Scan all markets by Octagon model edge
+  search [theme|ticker|query]   Find markets (Octagon when key set, else local)
+  search --sort-by volume_24h   Top-N by liquidity
+  search --aggregate-by series  Roll up results to series level
+  search themes                 (Legacy) Kalshi category labels
+  search edge [--min-edge N]    Edge ranking (Octagon when key set, else local)
+  similar <ticker>              Semantic neighbors (embedding distance)
+  similar -q "free text"        Semantic search by natural-language query
+  clusters [--label X]          Browse thematic clusters
+  clusters <id>                 List markets in a cluster
+  clusters --behavioral         Behavioral clusters (30-day return vectors)
+  clusters --ranked             Rank clusters by historical basket return
+  peers <ticker>                Find markets in the same cluster
+  events                        Octagon events (event ↔ outcome ladder)
+  events <event_ticker>         Drill into one event's outcome probabilities
+  series                        Series rollup with 24h vol, market count
+  series <SERIES>               Sub-markets in one series
+  series candles <SERIES>       Series NAV (basket of top sub-markets)
+  catalysts upcoming --days 30  Markets closing soon, grouped by week
   watch <ticker>                Live price/orderbook feed
   watch --theme <theme>         Continuous theme scan (Ctrl+C to stop)
   watch --refresh               Force index rebuild before watching
 
+Editorial themes (narrative registry):
+  themes                        List registered editorial themes
+  themes import                 Seed from data/themes_seo.json (25 starter themes)
+  themes show <name>            Drill into one theme
+  themes report                 25-theme dashboard with SEO + liquidity
+  themes audit                  Flag dead themes (high SEO + zero volume)
+  themes overlap                Cross-theme dedupe report
+  themes create/delete/add-series/remove-series/set-search-volume/export
+
+Portfolio construction:
+  correlate <t1> <t2> [...]     Pairwise Pearson correlation matrix
+  basket build [filters] -n N   Diversified basket with cluster + correlation caps
+  basket backtest --tickers ... NAV summary with Sharpe, max DD, win rate
+  basket size --bankroll $ --probs ...   Fractional Kelly sizing for picked legs
+  basket candles --tickers ...  OHLC bars for a weighted basket NAV
+
 Analysis & Trading:
   analyze <ticker>              Full report: edge, drivers, Kelly sizing
   analyze <ticker> --refresh    Force fresh Octagon report
@@ -185,14 +440,44 @@ Quick start:
   /watch --theme crypto   Continuous scan across a theme
 
 Discovery:
-  /search [theme|ticker|query]   Find markets by keyword or theme
-  /search --refresh <query>      Force index rebuild then search
-  /search themes                 List all themes and subcategories
-  /search edge [--min-edge N]    Scan all markets by Octagon model edge
+  /search [theme|ticker|query]   Find markets (Octagon when key set, else local)
+  /search --sort-by volume_24h   Top-N by liquidity
+  /search --aggregate-by series  Roll up results to series level
+  /search themes                 (Legacy) Kalshi category labels
+  /search edge [--min-edge N]    Edge ranking (Octagon when key set, else local)
+  /similar <ticker>              Semantic neighbors (embedding distance)
+  /similar -q "free text"        Semantic search by natural-language query
+  /clusters [--label X]          Browse thematic clusters
+  /clusters <id>                 List markets in a cluster
+  /clusters --behavioral         Behavioral clusters (30-day return vectors)
+  /clusters --ranked             Rank clusters by historical basket return
+  /peers <ticker>                Find markets in the same cluster
+  /events                        Octagon events (event ↔ outcome ladder)
+  /events <event_ticker>         Drill into one event's outcome probabilities
+  /series                        Series rollup with 24h vol, market count
+  /series <SERIES>               Sub-markets in one series
+  /series candles <SERIES>       Series NAV (basket of top sub-markets)
+  /catalysts upcoming --days 30  Markets closing soon, grouped by week
   /watch <ticker>                Live price/orderbook feed
   /watch --theme <theme>         Continuous theme scan (Esc to stop)
   /watch --refresh               Force index rebuild before watching
 
+Editorial themes (narrative registry):
+  /themes                        List registered editorial themes
+  /themes import                 Seed from data/themes_seo.json (25 starter themes)
+  /themes show <name>            Drill into one theme
+  /themes report                 25-theme dashboard with SEO + liquidity
+  /themes audit                  Flag dead themes (high SEO + zero volume)
+  /themes overlap                Cross-theme dedupe report
+  /themes create/delete/add-series/remove-series/set-search-volume/export
+
+Portfolio construction:
+  /correlate <t1> <t2> [...]     Pairwise Pearson correlation matrix
+  /basket build [filters] -n N   Diversified basket with cluster + correlation caps
+  /basket backtest --tickers ... NAV summary with Sharpe, max DD, win rate
+  /basket size --bankroll $ --probs ...   Fractional Kelly sizing for picked legs
+  /basket candles --tickers ...  OHLC bars for a weighted basket NAV
+
 Analysis:
   /backtest                      Model accuracy scorecard + live edge scanner
   /analyze <ticker>              Full report: edge, drivers, Kelly sizing

package/src/commands/index.ts

@@ -16,7 +16,10 @@ function defaultArgs(overrides: Partial<ParsedArgs>): ParsedArgs {
     subcommand: 'chat', positionalArgs: [], json: false,
     live: false, refresh: false, report: false, dryRun: false,
     verbose: false, performance: false, resolved: false,
-    unresolved: false, parseErrors: [],
+    unresolved: false,
+    behavioral: false, ranked: false, showCluster: false,
+    activeOnly: false, cells: false, autoProbs: false,
+    parseErrors: [],
     ...overrides,
   };
 }
@@ -27,6 +30,16 @@ import { reviewPortfolio, formatReviewHuman } from './review.js';
 import { buildHelp, validateTradeArgs } from './help.js';
 import { fetchMarketQuote } from './helpers.js';
 import { trackEvent } from '../utils/telemetry.js';
+import { parseArgs } from './parse-args.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 { handleEvents, formatEventsHuman } from './events.js';
+import { handleSeries, formatSeriesHuman } from './series.js';
+import { handleEditorialThemes, formatEditorialThemesHuman } from './editorial-themes.js';
+import { handleCatalysts, formatCatalystsHuman } from './catalysts.js';
 
 export interface CommandResult {
   output: string;
@@ -49,7 +62,28 @@ export async function handleSlashCommand(input: string): Promise<CommandResult |
   const parts = trimmed.slice(1).trim().split(/\s+/);
   const command = parts[0]?.toLowerCase();
   const args = parts.slice(1);
-  trackEvent('slash_command', { command: command ?? '' });
+  // Enrich Octagon-Kalshi commands with subview/mode flags so analytics can
+  // distinguish e.g. "basket build" vs "basket backtest", or thematic vs
+  // behavioral clusters. Outer command name is always tracked.
+  const slashMeta: Record<string, string | boolean> = { command: command ?? '' };
+  if (command === 'basket') {
+    const sub = args[0]?.toLowerCase();
+    if (sub === 'build' || sub === 'backtest' || sub === 'size' || sub === 'candles') {
+      slashMeta.subview = sub;
+    }
+    slashMeta.kelly_sizing = args.includes('--bankroll');
+  } else if (command === 'clusters') {
+    slashMeta.behavioral = args.includes('--behavioral');
+    slashMeta.ranked = args.includes('--ranked');
+  } else if (command === 'peers') {
+    slashMeta.behavioral = args.includes('--behavioral');
+    slashMeta.show_cluster = args.includes('--show-cluster');
+  } else if (command === 'similar') {
+    slashMeta.anchor = args.includes('-q') || args.includes('--query') ? 'query' : 'ticker';
+  } else if (command === 'search') {
+    slashMeta.remote = !!process.env.OCTAGON_API_KEY;
+  }
+  trackEvent('slash_command', slashMeta);
 
   switch (command) {
     case 'help': {
@@ -79,11 +113,24 @@ export async function handleSlashCommand(input: string): Promise<CommandResult |
     case 'cancel':
       return handleCancel(args[0]);
 
-    // ─── /search themes (inline) ─────────────────────────────────────
-    // Note: /search <non-themes> is handled in cli.ts via browseController
+    // ─── /themes (editorial registry) ────────────────────────────────
+    // The bare /themes call now hits the editorial-themes registry. Legacy
+    // "Kalshi category labels" is still reachable via /search themes.
     case 'themes': {
-      const resp = await handleThemes(defaultArgs({ subcommand: 'themes' }));
-      return { output: formatThemesHuman(resp.data) };
+      const parsed = parseArgs(['themes', ...args]);
+      const sub = parsed.positionalArgs[0]?.toLowerCase();
+      const isAsync = sub === 'report' || sub === 'audit';
+      if (!isAsync) {
+        const resp = await handleEditorialThemes(parsed);
+        return { output: resp.ok ? formatEditorialThemesHuman(resp.data) : (resp.error?.message ?? 'themes failed') };
+      }
+      return {
+        output: `Building themes ${sub} (this pulls the full Kalshi universe)...`,
+        asyncFollowUp: async () => {
+          const resp = await handleEditorialThemes(parsed);
+          return resp.ok ? formatEditorialThemesHuman(resp.data) : (resp.error?.message ?? 'themes failed');
+        },
+      };
     }
 
     // ─── /analyze ────────────────────────────────────────────────────
@@ -126,6 +173,90 @@ export async function handleSlashCommand(input: string): Promise<CommandResult |
       };
     }
 
+    // ─── Octagon Kalshi search/clusters/basket ───────────────────────
+    case 'similar': {
+      const parsed = parseArgs(['similar', ...args]);
+      return {
+        output: 'Querying Octagon for similar markets...',
+        asyncFollowUp: async () => {
+          const resp = await handleSimilar(parsed);
+          return resp.ok ? formatSimilarHuman(resp.data) : (resp.error?.message ?? 'similar failed');
+        },
+      };
+    }
+    case 'clusters': {
+      const parsed = parseArgs(['clusters', ...args]);
+      return {
+        output: 'Querying Octagon for clusters...',
+        asyncFollowUp: async () => {
+          const resp = await handleClusters(parsed);
+          return resp.ok ? formatClustersHuman(resp.data) : (resp.error?.message ?? 'clusters failed');
+        },
+      };
+    }
+    case 'peers': {
+      const parsed = parseArgs(['peers', ...args]);
+      return {
+        output: 'Querying Octagon for cluster peers...',
+        asyncFollowUp: async () => {
+          const resp = await handlePeers(parsed);
+          return resp.ok ? formatPeersHuman(resp.data) : (resp.error?.message ?? 'peers failed');
+        },
+      };
+    }
+    case 'correlate': {
+      const parsed = parseArgs(['correlate', ...args]);
+      return {
+        output: 'Computing correlation matrix...',
+        asyncFollowUp: async () => {
+          const resp = await handleCorrelate(parsed);
+          return resp.ok ? formatCorrelationHuman(resp.data) : (resp.error?.message ?? 'correlate failed');
+        },
+      };
+    }
+    case 'basket': {
+      const parsed = parseArgs(['basket', ...args]);
+      const sub = parsed.positionalArgs[0] ?? '';
+      return {
+        output: `Running basket ${sub || '(no subcommand)'}...`,
+        asyncFollowUp: async () => {
+          const resp = await handleBasket(parsed);
+          return resp.ok ? formatBasketHuman(resp.data) : (resp.error?.message ?? 'basket failed');
+        },
+      };
+    }
+    case 'events': {
+      const parsed = parseArgs(['events', ...args]);
+      return {
+        output: 'Querying Octagon events...',
+        asyncFollowUp: async () => {
+          const resp = await handleEvents(parsed);
+          return resp.ok ? formatEventsHuman(resp.data) : (resp.error?.message ?? 'events failed');
+        },
+      };
+    }
+    case 'series': {
+      const parsed = parseArgs(['series', ...args]);
+      const sub = parsed.positionalArgs[0]?.toLowerCase();
+      return {
+        output: sub === 'candles' ? 'Building series NAV...' : 'Rolling up Kalshi series...',
+        asyncFollowUp: async () => {
+          const resp = await handleSeries(parsed);
+          return resp.ok ? formatSeriesHuman(resp.data) : (resp.error?.message ?? 'series failed');
+        },
+      };
+    }
+    case 'catalysts': {
+      const parsed = parseArgs(['catalysts', ...args]);
+      return {
+        output: 'Loading upcoming catalysts...',
+        asyncFollowUp: async () => {
+          const resp = await handleCatalysts(parsed);
+          return resp.ok ? formatCatalystsHuman(resp.data) : (resp.error?.message ?? 'catalysts failed');
+        },
+      };
+    }
+
     case 'config':
       // Fall through to agent — better handled by the LLM
       return null;