kalshi-trading-bot-cli 2.1.3 → 2.1.5

package/README.md

@@ -28,6 +28,8 @@ That's it — no clone, no install. The setup wizard runs automatically on first
 
 Prefer a global install? `bun add -g kalshi-trading-bot-cli` then run `kalshi`.
 
+> **Scripting and agent use** — for parallel invocations, `--json` consumers, or anything that pipes our output: **install globally and use the `kalshi` binary**, not `bunx`. See [Scripting & Parallel Use](#scripting--parallel-use) below for the gory details.
+
 Or work from a clone:
 
 ```bash
@@ -114,8 +116,31 @@ Type help for commands, or just ask a question.
 
 | Command | Description |
 |---------|-------------|
-| `search [theme\|ticker\|query]` | Find markets by keyword or theme |
-| `search edge [--min-edge N]` | Scan all markets by model edge |
+| `search [theme\|ticker\|query]` | Find markets by keyword or theme (Octagon-backed when key set) |
+| `search edge [--min-edge N]` | Scan all markets by model edge (Octagon `markets-with-edge`) |
+| `similar <ticker\|"query">` | Semantic neighbors via Octagon embeddings |
+| `clusters [--label X]` | Browse thematic clusters of the Kalshi universe |
+| `clusters <id>` | List markets inside a cluster |
+| `clusters --behavioral` | Behavioral clusters by 30-day return vectors |
+| `clusters --ranked` | Rank clusters by historical basket return |
+| `peers <ticker>` | Markets in the same cluster as a ticker |
+| `correlate <t1> <t2> [...]` | Pairwise Pearson correlation matrix |
+| `basket build` | Diversified basket with cluster + correlation caps |
+| `basket backtest` | NAV summary: total return, Sharpe, max drawdown, win rate |
+| `basket size` | Fractional Kelly sizing for picked legs |
+| `basket candles` | OHLC bars for a weighted basket NAV |
+| `basket validate` | One-call portfolio diagnostics (clusters, correlations, calendar clashes, warnings) |
+| `basket size --auto-probs` | Auto-fetch model probabilities via `markets/edge` and Kelly-size |
+| `basket backtest --theme <name>` | Resolve an editorial theme to a NAV basket and backtest it |
+| `series events <ticker>` | List events inside a series |
+| `events` / `events <ticker>` | Octagon events list + outcome ladder per event |
+| `series` / `series <ticker>` | Kalshi series rollup (24h vol, market count) |
+| `series candles <ticker>` | Series-level NAV (basket of top sub-markets) |
+| `catalysts upcoming --days N` | Markets closing in the next N days, grouped by week |
+| `themes` (registry) | Editorial narrative buckets — list/show/import/create/delete/add-series |
+| `themes report` | 25-theme dashboard with SEO + liquidity |
+| `themes audit` | Flag dead themes (high SEO + zero volume) |
+| `themes overlap` | Cross-theme dedupe report |
 | `analyze <ticker>` | Deep analysis: edge, drivers, Kelly sizing |
 | `watch <ticker>` | Live price and orderbook feed |
 | `watch --theme <theme>` | Continuous theme scan |
@@ -151,6 +176,143 @@ Type help for commands, or just ask a question.
 | `--min-price <n>` | Min contract price, 0-100 scale (backtest, default 5) |
 | `--max-price <n>` | Max contract price, 0-100 scale (backtest, default 95) |
 | `--export <path>` | Export per-market CSV (backtest) |
+| `--top-k <n>` | Number of neighbors (similar); legs per cluster (clusters --ranked) |
+| `--behavioral` | Use behavioral clustering (clusters, peers) |
+| `--ranked` | Rank clusters by historical basket return (clusters) |
+| `--label <substr,...>` | Filter by cluster label substring (clusters, basket build) |
+| `--close-before <iso>` | Only markets closing before this timestamp |
+| `--window-days <n>` | Correlation lookback (correlate; basket build) |
+| `--correlation-interval <1h\|1d>` | Override candle bin size for correlate |
+| `--timeframe <1w\|1m\|3m\|6m\|1y>` | Window/bin size for basket commands |
+| `--weights <csv>` | Comma-separated weights for basket backtest/candles |
+| `--bankroll <usd>` | Bankroll for Kelly sizing (basket size/build) |
+| `--kelly <0-1>` | Kelly multiplier (default 0.25) |
+| `-n <n>` | Basket size requested (basket build) |
+| `--max-per-cluster <n>` | Cap legs per thematic cluster (basket build) |
+| `--max-corr <-1..1>` | Pairwise correlation cap (basket build) |
+| `--min-return <n>` | Minimum total_return for clusters --ranked |
+| `--series <ticker>` | Filter to a Kalshi series (search, similar, basket) |
+| `--sort-by <key>` | Sort key for search edge: edge_pp \| expected_return \| total_volume \| model_probability |
+| `--probs <csv>` | Per-leg probabilities, e.g. `KX-A:0.62,KX-B:0.55` |
+| `--tickers <csv>` | Comma-separated tickers (correlate, basket backtest/candles) |
+| `-q "text"` | Free-text anchor for similar / basket build |
+| `--show-cluster` | Print cluster membership only (peers) |
+| `--theme <name>` | Resolve an editorial theme to a ticker list (basket backtest/candles/validate/size) |
+| `--aggregate-by series` | Roll up search results to the series level |
+| `--active-only` | Drop non-active markets (defensive flag — open universe by default) |
+| `--series-prefix <prefix>` | Server-side series prefix match (e.g. `KXBTC` matches KXBTCD, KXBTCY, ...) |
+| `--sides yes,no,yes` | Per-ticker side for `correlate` (sign-flipped) |
+| `--cells` | Include per-cell detail (overlap, reason) in `correlate` |
+| `--auto-probs` | `basket size`: auto-fetch model probabilities via `markets/edge` |
+
+### Discovery & Portfolio (Octagon-powered)
+
+The `search`, `similar`, `clusters`, `peers`, `correlate`, and `basket` commands turn the whole Kalshi universe into a queryable database. When `OCTAGON_API_KEY` is set the bot routes searches through Octagon's typed endpoints — semantic embedding lookups, nightly k-means clusters (thematic + behavioral), Pearson correlation matrices, and one-call diversified basket construction with cluster caps and pairwise-correlation gates. Without a key, `search` and `search edge` fall back to the local SQLite cache.
+
+```bash
+# Free-text + structured search (semantic full-text + filters)
+kalshi search "bitcoin price" --category crypto --min-volume 10000 --limit 20
+
+# Edge ranking from Octagon's latest run (server-side, no local pre-fetch)
+kalshi search edge --min-edge 5 --limit 10 --sort-by total_volume
+
+# Semantic neighbors — catches matches keyword search misses
+kalshi similar KXBTCD-26DEC31-T100000 --top-k 25
+kalshi similar -q "Will Bitcoin pierce six figures" --category crypto
+
+# Browse the universe by theme
+kalshi clusters --label fed                 # find Fed-decision clusters
+kalshi clusters 42                          # markets in cluster 42
+kalshi clusters --behavioral                # behavioral clusters (mean ret + vol)
+kalshi clusters --ranked --timeframe 1y --min-return 0.20 --top-k 5
+
+# Same-theme dedup
+kalshi peers KXBTCD-26DEC31-T100000 --kind thematic --limit 50
+kalshi peers KXBTCD-26DEC31-T100000 --show-cluster     # which cluster does this belong to?
+
+# Pairwise correlation matrix — most-uncorrelated pairs first
+kalshi correlate KXBTCD-... KXETHU-... KXSOL-... --window-days 90
+
+# Build a diversified basket (one HTTP call — universe → cluster cap → corr cap → sizing)
+kalshi basket build --category crypto --min-volume 10000 \
+  -n 8 --max-per-cluster 2 --max-corr 0.6 \
+  --bankroll 1000 --kelly 0.25 \
+  --probs KXBTCD-...:0.62,KXETHU-...:0.58
+
+# "Find me 5 uncorrelated bets on macro themes" — one HTTP call
+kalshi basket build --label fed,cpi,fomc,gdp,jobs \
+  -n 5 --max-per-cluster 1 --max-corr 0.4
+
+# Backtest a basket and read total_return / Sharpe / max DD directly
+kalshi basket backtest --tickers KX-A,KX-B,KX-C --weights 0.4,0.4,0.2 --timeframe 1y
+
+# Kelly-size legs you've already picked
+kalshi basket size --bankroll 1000 --kelly 0.25 --probs KX-A:0.62,KX-B:0.55
+
+# Or let Octagon's model fill in the probabilities for you
+kalshi basket size --auto-probs --tickers KX-A,KX-B,KX-C --bankroll 1000 --kelly 0.25
+kalshi basket size --auto-probs --theme "AI Race Milestones" --bankroll 1000 --kelly 0.25
+
+# Diversified basket builder over an explicit candidate pool
+kalshi basket build --tickers KX-A,KX-B,KX-C,KX-D -n 3 --max-per-cluster 1 --max-corr 0.5
+kalshi basket build --theme "Iran Escalation" -n 4 --max-per-cluster 1 --max-corr 0.5 --auto-probs --bankroll 1000
+
+# Sanity-check a proposed basket before placing orders (one call, server-side)
+kalshi basket validate --tickers KX-A,KX-B --bankroll 1000 --max-corr 0.5
+kalshi basket validate --theme "Iran Escalation" --bankroll 1000
+#   → cluster breakdown, pairwise correlations (top by |corr|), calendar
+#     clashes (weeks where many legs resolve), duplicate underliers, warnings.
+```
+
+### Editorial Theme Dashboard
+
+`themes` is a local registry of editorial narrative buckets (e.g. "AI Race Milestones", "Iran Escalation") that maps to lists of Kalshi series with optional monthly search-volume annotations. The bot ships with a 25-theme seed dataset in `data/themes_seo.json`. Distinct from Octagon's ML clusters — these are *narratives* you curate.
+
+```bash
+# Seed from the included starter dataset (25 themes, 173 series mappings)
+kalshi themes import
+
+# Browse the registry
+kalshi themes list
+kalshi themes show "Iran Escalation"
+
+# THE dashboard view: 25-theme grid with SEO + liquidity
+kalshi themes report
+
+# Flag dead themes (high SEO + zero active Kalshi inventory)
+kalshi themes audit
+#   → Epstein / Celebrity Trials   STALE         4.3M searches, 0 active markets
+#   → RFK Jr Changes Health        NO_INVENTORY  422k searches, 0 active markets
+#   → AI Race Milestones           TRADEABLE     138M searches, 28 active mkts
+#   → Bitcoin Breakout             TRADEABLE     29k searches, 270 active mkts
+
+# Cross-theme dedupe (when a series belongs to multiple themes)
+kalshi themes overlap
+#   → KXUSAIRANAGREEMENT  Iran Escalation · Nuclear Renaissance
+#   → KXMORTGAGERATE      Fed Cuts Aggressively · Housing / Mortgage Crisis
+
+# Build/manage your own themes
+kalshi themes create "My Macro Hedge" --label "..." --tickers KXRECSSNBER,KXCPIYOY
+kalshi themes add-series "My Macro Hedge" KXFEDDECISION,KXU3
+kalshi themes set-search-volume "My Macro Hedge" 50000
+
+# Backtest an entire theme as a NAV basket (one top market per series)
+kalshi basket backtest --theme "Iran Escalation" --timeframe 3m
+kalshi basket candles --theme "Fed Cuts Aggressively" --timeframe 1y --json
+
+# Series-level rollup and NAV
+kalshi series list --min-volume 10000              # liquid series, ranked
+kalshi series KXBTCD --limit 10                    # drill in
+kalshi series candles KXBTCD --timeframe 3m        # series NAV momentum
+kalshi series search bitcoin --limit 10            # keyword → rollup
+
+# Event ↔ outcome ladder
+kalshi events --category Politics --limit 10       # top political events by volume
+kalshi events KXFEDCHAIRNOM-29                     # outcome probabilities + per-contract edge
+
+# Catalyst calendar
+kalshi catalysts upcoming --days 14 --min-volume 5000 --category Politics
+```
 
 ### Backtesting
 
@@ -180,8 +342,6 @@ kalshi backtest --export results.csv         # per-market detail
 Octagon Backtest — 15-day lookback (04/02 – 04/17)
 ══════════════════════════════════════════════════════════
 
-VERDICT: Model has edge (Skill +12.5% [CI: +4.1%, +20.8%]; ROI +7.8%)
-
   Events         83
   Markets        247   (142 resolved, 105 unresolved)
   Brier (Octagon)   0.168
@@ -205,12 +365,47 @@ UNRESOLVED (105 markets)
 
 Set `KALSHI_USE_DEMO=true` in your `.env` to use Kalshi's demo environment. All trades are simulated — no real money at risk.
 
+## Scripting & Parallel Use
+
+The `bunx kalshi-trading-bot-cli@latest …` form is great for one-off interactive use, but it has two gotchas when you script against it:
+
+**1. Install chatter leaks into `--json` output.** Bun prints lines like `Resolving dependencies` and `Saved lockfile` to stdout *before* our CLI runs, which corrupts JSON pipelines.
+
+**2. Parallel invocations race on the install cache.** Running multiple `bunx kalshi-trading-bot-cli@latest …` calls in parallel can fail with `Failed to link …: EEXIST` and `could not determine executable`. See [oven-sh/bun#12917](https://github.com/oven-sh/bun/issues/12917) for current upstream status — `bunx`'s ephemeral install path isn't covered by the `bun install` global-store fix, so the workarounds below are still the recommended path.
+
+**Recommended pattern for scripts and agents:**
+
+```bash
+# Install once globally — this is parallel-safe and emits no install chatter on subsequent runs
+bun add -g kalshi-trading-bot-cli
+
+# Then use the `kalshi` binary directly — fan out as much as you want
+parallel -j 30 'kalshi analyze {} --json > {}.json' ::: KXBTC-26APR-B95000 KXETH-… …
+```
+
+**If you must use `bunx`:**
+
+```bash
+# --silent suppresses Bun's install chatter (keeps your CLI's stdout clean)
+bunx --silent kalshi-trading-bot-cli@latest analyze KXBTC-26APR-B95000 --json
+
+# For parallel bunx, pre-warm the cache serially first to dodge the link race
+bunx --silent kalshi-trading-bot-cli@latest --version    # one-shot, populates cache
+parallel -j 30 'bunx --silent kalshi-trading-bot-cli@latest analyze {} --json' ::: KXBTC-… …
+```
+
+Keep `@latest` if you want auto-update on every invocation; drop it after the first run if you've pinned a version and want speed.
+
 ## Agent Usage
 
 Every command supports `--json` for structured output, making the bot easy to orchestrate from scripts or AI agents.
 
 ```bash
 kalshi search crypto --json
+kalshi similar KXBTC-26APR-B95000 --top-k 10 --json
+kalshi clusters --ranked --timeframe 1y --min-return 0.2 --json
+kalshi correlate KX-A KX-B KX-C --window-days 90 --json
+kalshi basket build --category crypto -n 8 --max-per-cluster 2 --max-corr 0.6 --json
 kalshi analyze KXBTC-26APR-B95000 --json
 kalshi buy KXBTC-26APR-B95000 3 58 --json
 kalshi portfolio --json
@@ -263,6 +458,20 @@ fi
 kalshi portfolio --json
 ```
 
+### Server-side basket construction
+
+For agents that want to skip the per-ticker analysis loop, the `basket build` command pushes universe selection, cluster diversification, correlation gating, and Kelly sizing server-side into a single HTTP call:
+
+```bash
+# Pull Octagon's edge ranking, build a diversified 8-leg crypto basket sized for $1000
+EDGE=$(kalshi search edge --category crypto --min-edge 5 --json | jq '.data.data')
+PROBS=$(echo "$EDGE" | jq -r 'map("\(.market_ticker):\(.model_probability/100)") | join(",")')
+
+kalshi basket build --category crypto --min-volume 10000 \
+  -n 8 --max-per-cluster 2 --max-corr 0.6 \
+  --bankroll 1000 --kelly 0.25 --probs "$PROBS" --json
+```
+
 The `watch --theme` command outputs NDJSON (one JSON object per scan cycle), suitable for streaming pipelines.
 
 ## Configuration
@@ -282,7 +491,7 @@ cp env.example ~/.kalshi-bot/.env
 | `KALSHI_API_KEY` | Kalshi API key ID |
 | `KALSHI_PRIVATE_KEY_FILE` | Path to your Kalshi RSA private key PEM file |
 | `OPENAI_API_KEY` | OpenAI API key (default model is GPT-5.4) |
-| `OCTAGON_API_KEY` | Octagon API key for deep research. Get one at [app.octagonai.co](https://app.octagonai.co) |
+| `OCTAGON_API_KEY` | Octagon API key. Powers deep research (`analyze`), edge scanning (`search edge`), and the Octagon-backed discovery + basket commands (`search`, `similar`, `clusters`, `peers`, `correlate`, `basket`). Get one at [app.octagonai.co](https://app.octagonai.co) |
 
 **Optional:**
 

package/data/themes_seo.json

@@ -0,0 +1,159 @@
+{
+  "_meta": {
+    "description": "Curated editorial themes for Kalshi prediction markets, ranked by Google search demand. Each theme maps to a list of Kalshi series tickers and carries a monthly search-volume estimate. Use `kalshi themes import data/themes_seo.json` to load. Volumes are point-in-time estimates; refresh quarterly.",
+    "version": "1.0",
+    "as_of": "2026-05-25"
+  },
+  "themes": [
+    {
+      "name": "AI Race Milestones",
+      "description": "Frontier model releases, AI infrastructure, training-compute and AGI predictions",
+      "search_volume": 138300000,
+      "series": ["KXLLM1", "KXIPOOPENAI", "KXAIREVIEW", "KXOAIANTH", "KXTECHRANKLISTAICODE", "KXH200CHINA", "KXGPT", "KXCLAUDE", "KXCODINGMODEL", "KXOAIHARDWARE", "KXCHAICUTS", "KXTOPAI", "KXBESTLLMCHINA"]
+    },
+    {
+      "name": "Elon Musk / Tesla / SpaceX",
+      "description": "Musk-empire markets: SpaceX IPO, Starship cadence, Tesla KPIs, Neuralink, wealth",
+      "search_volume": 8400000,
+      "series": ["KXIPOSPACEX", "KXSPACEXCOUNT", "KXSPACEXSTARSHIP", "KXMUSKWEALTH", "KXMUSKTRILLION", "KXTSLA", "KXIPOSTARLINK", "KXNEURALINKCOUNT", "KXTESLACAR", "KXSTARSHIPMARS", "KXSTARSHIPDOCK", "KXBLUESPACEX"]
+    },
+    {
+      "name": "Epstein / Celebrity Trials",
+      "description": "Massive SEO demand but thin Kalshi inventory — flag as STALE",
+      "search_volume": 4280000,
+      "series": ["KXEPSTEINLIST", "KXRELEASEMAXWELL", "KXEPSTEIN"]
+    },
+    {
+      "name": "Government Dysfunction",
+      "description": "House Speaker fights, filibuster reform, government shutdowns",
+      "search_volume": 3730000,
+      "series": ["KXNEXTSPEAKER", "KXFBUSTER", "KXNUMSHUTDOWNS"]
+    },
+    {
+      "name": "FDA / Pharma Approvals",
+      "description": "Drug approvals, psychedelic milestones, FDA commissioner pick",
+      "search_volume": 3070000,
+      "series": ["KXFDAAPPROVALPSYCHEDELIC", "KXFDANOM", "KXFDAAPPROVE", "KXFDARETATRUTIDE", "KXFDAANNOUNCE", "KXFDAAPPROVALDATECMPS", "KXFDAAPPROVALDATENTLA"]
+    },
+    {
+      "name": "Iran Escalation",
+      "description": "Hormuz traffic, US-Iran nuclear deal, oil & gas price ladders",
+      "search_volume": 1140000,
+      "series": ["KXHORMUZNORM", "KXUSAIRANAGREEMENT", "KXAAAGASM", "KXWTIW", "KXAAAGASW", "KXWTI", "KXAAAGASD", "KXBRENTW", "KXHORMUZWEEKLY", "KXBRENTMON", "KXWTIMINM", "KXAAAGASMAX"]
+    },
+    {
+      "name": "Gaza War Wraps",
+      "description": "Israel rate decisions, Netanyahu / next PM, post-war politics",
+      "search_volume": 1090000,
+      "series": ["KXCBDISRAEL", "KXNETANYAHUPARDON", "KXNEXTISRAELPM", "KXISRAELPM", "KXISLGAME", "KXKANYEISRAEL"]
+    },
+    {
+      "name": "Trump Survives Politically",
+      "description": "Approval ratings, midterm dynamics, 25th Amendment / impeachment",
+      "search_volume": 505000,
+      "series": ["KXVOTEHUBTRUMPUPDOWN", "KXMIDTERMMOV", "KXMIDTERMVOTETURN", "KXRUNBYMIDTERM", "KXTRUMPREMOVE", "KXMOCTRUMP25", "KXAMEND25", "KXLEAVEDUNN", "KXLEAVEMILLS"]
+    },
+    {
+      "name": "RFK Jr Changes Health",
+      "description": "Huge SEO but zero active Kalshi inventory — AVOID",
+      "search_volume": 422000,
+      "series": []
+    },
+    {
+      "name": "Nuclear Renaissance",
+      "description": "Reactor licenses, criticality milestones, data-center nuclear, fusion",
+      "search_volume": 382000,
+      "series": ["KXUSAIRANAGREEMENT", "KXCRITICALITY", "KXREACTOR", "KXDATACENTER", "KXFUSION"]
+    },
+    {
+      "name": "Fed Cuts Aggressively",
+      "description": "Fed meeting decisions, CPI prints, rate-cut paths, mortgage rates",
+      "search_volume": 340000,
+      "series": ["KXFEDDECISION", "KXFEDHIKE", "KXFED", "KXCPIYOY", "KXMORTGAGERATE", "KXCPI", "KXECONSTATCPIYOY", "KXLCPIMAXYOY", "KXCBDISRAEL", "KXRATECUT", "KXFOMCDISSENTCOUNT", "KXUKCPIYOY"]
+    },
+    {
+      "name": "SCOTUS Rulings",
+      "description": "Birthright citizenship, trans sports ban, tariff cases, justice changes",
+      "search_volume": 334000,
+      "series": ["KX14AMENDCASE", "KXWATSONRNC", "KXSCOTUSRESIGN", "KXTRANSGENDERSPORTSBAN", "KXTRUMPTARIFFHEAR", "KXSCOTUSN", "KXTRUMPSLAUGHTERVOTE", "KXTRUMPVSLAUGHTER", "KXSCOTUSCERT3RD", "KXSCOTUSMARIJUANAGUN"]
+    },
+    {
+      "name": "Housing / Mortgage Crisis",
+      "description": "Mortgage rates, new home sales, hedge-fund housing tax, starts",
+      "search_volume": 291000,
+      "series": ["KXMORTGAGERATE", "KXHFHOUSING", "KXNHSALES", "KXHOUSINGSTART", "KXEHSALES"]
+    },
+    {
+      "name": "US-China Decoupling",
+      "description": "Tariffs, chip export controls, Taiwan posture, PRC PMI",
+      "search_volume": 211000,
+      "series": ["KXTARIFFCHECKS", "KXNEWTARIFFS", "KXH200CHINA", "KXTAIWANLVL4", "KXTARIFFRATEPRC", "KXBEEFTARIFF", "KXTARIFFRATEINDIA", "KXF1CHINA", "KXBESTLLMCHINA", "KXCHNBSPMI", "KXTRUMPTARIFFHEAR", "KXRECOGROC"]
+    },
+    {
+      "name": "TikTok Ban",
+      "description": "Story died — high SEO with zero active inventory. AVOID",
+      "search_volume": 173000,
+      "series": []
+    },
+    {
+      "name": "Immigration Crackdown",
+      "description": "ICE funding, deportations, border encounters",
+      "search_volume": 163000,
+      "series": ["KXICEERO", "KXSWENCOUNTERS", "KXICERENAME", "KXDEPORTATIONS"]
+    },
+    {
+      "name": "Stock Market Crash / S&P",
+      "description": "S&P 500 / NASDAQ ranges, unemployment, NBER recession",
+      "search_volume": 132000,
+      "series": ["KXINXY", "KXINXMAXY", "KXNASDAQ100Y", "KXU3", "KXRECSSNBER", "KXINX", "KXNASDAQ100MAXY", "KXINXVSNDQ100", "KXSP500ADDQ", "KXU3MAX", "KXNASDAQ100POS", "KXUE"]
+    },
+    {
+      "name": "Crypto Regulation",
+      "description": "Single market, low volume — likely STALE",
+      "search_volume": 79000,
+      "series": ["KXCRYPTOCAPGAIN"]
+    },
+    {
+      "name": "Climate / EV Policy Reversal",
+      "description": "Truflation EV, IFO sentiment, climate-goal markets",
+      "search_volume": 60000,
+      "series": ["KXTRUEV", "KXDEIFO", "KXINDIACLIMATE", "KXUSCLIMATE", "KXEVSHARE", "KXEUCLIMATE"]
+    },
+    {
+      "name": "No 2026 Recession",
+      "description": "Unemployment + recession ladders — overlaps Stock Market Crash",
+      "search_volume": 48000,
+      "series": ["KXU3", "KXRECSSNBER", "KXU3MAX", "KXUE", "KXECONSTATU3", "KXNBERRECESSQ", "KXIMFRECESS", "KXBRAZILU"]
+    },
+    {
+      "name": "Russia-Ukraine Ends",
+      "description": "Zelensky/Putin summit, Russia rate decisions, post-war politics",
+      "search_volume": 44000,
+      "series": ["KXZELENSKYPUTIN", "KXCBDECISIONRUSSIA", "KXZELENSKYYOUT", "KXUKRAINEEU", "KXPUTINZELENSKYYLOCATION"]
+    },
+    {
+      "name": "Bitcoin Breakout",
+      "description": "Deepest crypto inventory: BTC/ETH price ladders, one-touch markets",
+      "search_volume": 29000,
+      "series": ["KXBTCD", "KXETHMAXY", "KXBTCY", "KXBTCMAX100", "KXETHD", "KXBTCMAX150", "KXBTCMAXMON", "KXBTCMINMON", "KXBTC", "KXBTCMINY", "KXETH", "KXCRYPTOSTRUCTURE"]
+    },
+    {
+      "name": "Trump Cabinet Shake-up",
+      "description": "Hegseth, McConnell, Trump firings, cabinet exits",
+      "search_volume": 22000,
+      "series": ["KXHEGSETHOUT", "KXCABOUT", "KXRETIREMM", "KXTRUMPRESIGN", "KXSCOTUSRESIGN", "KXTRYFIREPOWELL", "KXTRUMPFIRE", "KXVANCEPAKISTAN", "KXJIMMYKIMMELFIRED", "KXHEGSETHANNOUNCEOUT", "KXIMPEACHCABINET", "KXLEAVECONGRESS"]
+    },
+    {
+      "name": "Putin Out",
+      "description": "Thin inventory — overlaps Russia-Ukraine Ends",
+      "search_volume": 4700,
+      "series": ["KXZELENSKYPUTIN", "KXPUTINZELENSKYYLOCATION"]
+    },
+    {
+      "name": "Weed Rescheduled",
+      "description": "Thin overlap with FDA/SCOTUS themes",
+      "search_volume": 1600,
+      "series": ["KXFDAAPPROVALPSYCHEDELIC", "KXSCOTUSMARIJUANAGUN"]
+    }
+  ]
+}

package/env.example

@@ -24,8 +24,11 @@ GOOGLE_API_KEY=your-google-api-key
 XAI_API_KEY=your-xai-api-key
 OPENROUTER_API_KEY=your-openrouter-api-key
 
-# Octagon AI — required for /scan, /watch, and deep research
-# Get a key at https://app.octagonai.co
+# Octagon AI — required for deep research (/analyze, /watch, /scan) AND for
+# the Octagon-backed discovery + basket commands: /search, /search edge,
+# /similar, /clusters, /peers, /correlate, /basket. Without a key, /search
+# and /search edge fall back to the local SQLite cache; the others require
+# the key. Get one at https://app.octagonai.co
 OCTAGON_API_KEY=your-octagon-api-key
 
 # ── Optional ─────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kalshi-trading-bot-cli",
-  "version": "2.1.3",
+  "version": "2.1.5",
   "description": "Kalshi Trading Bot CLI - AI-powered prediction market terminal.",
   "license": "MIT",
   "author": "Octagon AI, Inc.",

package/src/backtest/renderer.ts

@@ -37,8 +37,6 @@ export function formatBacktestHuman(result: BacktestResult, opts?: FormatOpts):
   }
 
   // Unified scorecard
-  lines.push(`VERDICT: ${result.verdict.summary}`);
-  lines.push('');
   lines.push(`  Events         ${result.events_scored}`);
   lines.push(`  Markets        ${result.markets_resolved + result.markets_unresolved}   (${result.markets_resolved} resolved, ${result.markets_unresolved} unresolved)`);
   lines.push('');

package/src/cli.ts

@@ -354,6 +354,15 @@ export async function runCli(options?: { forceSetup?: boolean }) {
   const helpTopicCompletions = (typed: string): AutocompleteItem[] | null => {
     const topics = [
       { value: 'search', label: 'search', description: 'Discovery commands' },
+      { value: 'similar', label: 'similar', description: 'Semantic market search (Octagon)' },
+      { value: 'clusters', label: 'clusters', description: 'Browse thematic & behavioral clusters' },
+      { value: 'peers', label: 'peers', description: 'Cluster peers for a ticker' },
+      { value: 'correlate', label: 'correlate', description: 'Pairwise correlation matrix' },
+      { value: 'basket', label: 'basket', description: 'Build / backtest / size baskets' },
+      { value: 'events', label: 'events', description: 'Octagon events (event ↔ outcome ladder)' },
+      { value: 'series', label: 'series', description: 'Series rollup / NAV' },
+      { value: 'catalysts', label: 'catalysts', description: 'Upcoming market closes by week' },
+      { value: 'themes', label: 'themes', description: 'Editorial narrative registry + dashboard' },
       { value: 'portfolio', label: 'portfolio', description: 'Account state' },
       { value: 'analyze', label: 'analyze', description: 'Market analysis' },
       { value: 'watch', label: 'watch', description: 'Live monitoring' },
@@ -362,6 +371,7 @@ export async function runCli(options?: { forceSetup?: boolean }) {
       { value: 'cancel', label: 'cancel', description: 'Cancel an order' },
       { value: 'backtest', label: 'backtest', description: 'Model accuracy & edge scanner' },
       { value: 'help', label: 'help', description: 'Show help' },
+      { value: 'scripting', label: 'scripting', description: 'Tips for agents, pipelines, parallel use' },
       { value: 'setup', label: 'setup', description: 'Re-run setup wizard' },
     ];
     if (!typed) return topics;
@@ -394,6 +404,85 @@ export async function runCli(options?: { forceSetup?: boolean }) {
       const lower = typed.toLowerCase();
       return opts.filter(o => o.value.toLowerCase().includes(lower));
     }},
+    // Octagon Kalshi search/clusters/basket
+    { name: 'similar', description: 'Semantic market search by ticker or query', getArgumentCompletions: (typed: string): AutocompleteItem[] | null => {
+      const opts = [
+        { value: '<ticker>', label: '<ticker>', description: 'Anchor by ticker (no embedding call)' },
+        { value: '-q "query text"', label: '-q "query text"', description: 'Anchor by free-text (server-side embed)' },
+        { value: '--top-k 25', label: '--top-k 25', description: 'Number of neighbors (default 25)' },
+        { value: '--category crypto', label: '--category crypto', description: 'Filter by category' },
+        { value: '--min-volume 10000', label: '--min-volume 10000', description: '24h volume floor' },
+      ];
+      if (!typed) return opts;
+      return opts.filter(o => o.value.toLowerCase().includes(typed.toLowerCase()));
+    }},
+    { name: 'clusters', description: 'Browse thematic & behavioral clusters', getArgumentCompletions: (typed: string): AutocompleteItem[] | null => {
+      const opts = [
+        { value: '--label fed', label: '--label fed', description: 'Filter by label substring' },
+        { value: '--behavioral', label: '--behavioral', description: 'Behavioral clusters (30-day return vectors)' },
+        { value: '--ranked', label: '--ranked', description: 'Rank clusters by historical basket return' },
+        { value: '--ranked --timeframe 1y --min-return 0.20', label: '--ranked --timeframe 1y --min-return 0.20', description: 'Top-return baskets, 1y window' },
+        { value: '<cluster_id>', label: '<cluster_id>', description: 'List markets in a specific cluster' },
+      ];
+      if (!typed) return opts;
+      return opts.filter(o => o.value.toLowerCase().includes(typed.toLowerCase()));
+    }},
+    { name: 'peers', description: 'Find markets in the same cluster as a ticker', getArgumentCompletions: usageHint('<ticker> [--behavioral] [--limit N] [--show-cluster]', 'e.g. KXBTCD-26DEC31-T100000 --limit 20') },
+    { name: 'correlate', description: 'Pairwise correlation matrix (2-100 tickers)', getArgumentCompletions: usageHint('<ticker1> <ticker2> [...] [--window-days N]', 'e.g. KXA KXB KXC --window-days 90') },
+    { name: 'events', description: 'Octagon events — outcome ladder per event', getArgumentCompletions: usageHint('<event_ticker> | --category Politics | --min-volume 10000', 'e.g. KXFEDCHAIRNOM-29 to drill in') },
+    { name: 'series', description: 'Kalshi series rollup (24h vol, market count)', getArgumentCompletions: (typed: string): AutocompleteItem[] | null => {
+      const opts = [
+        { value: '<series_ticker>', label: '<series_ticker>', description: 'Drill into one series (e.g. KXBTCD)' },
+        { value: 'search <query>', label: 'search <query>', description: 'Keyword search rolled up by series' },
+        { value: 'candles <series_ticker> --timeframe 3m', label: 'candles <SERIES>', description: 'Series NAV basket' },
+        { value: '--min-volume 10000', label: '--min-volume 10000', description: 'Liquidity floor' },
+        { value: '--category Crypto', label: '--category Crypto', description: 'Filter by category' },
+      ];
+      if (!typed) return opts;
+      return opts.filter(o => o.value.toLowerCase().includes(typed.toLowerCase()));
+    }},
+    { name: 'catalysts', description: 'Upcoming market closes grouped by week', getArgumentCompletions: (typed: string): AutocompleteItem[] | null => {
+      const opts = [
+        { value: 'upcoming', label: 'upcoming', description: 'Next 30 days (default)' },
+        { value: 'upcoming --days 7', label: '--days 7', description: 'Next week' },
+        { value: 'upcoming --days 14 --min-volume 5000', label: '--days 14 --min-volume 5000', description: 'Two weeks, liquid only' },
+        { value: 'upcoming --category Politics', label: '--category Politics', description: 'By category' },
+      ];
+      if (!typed) return opts;
+      return opts.filter(o => o.value.toLowerCase().includes(typed.toLowerCase()));
+    }},
+    { name: 'themes', description: 'Editorial themes registry: import, report, audit, overlap', getArgumentCompletions: (typed: string): AutocompleteItem[] | null => {
+      const opts = [
+        { value: 'list', label: 'list', description: 'List registered themes' },
+        { value: 'import', label: 'import', description: 'Seed from data/themes_seo.json' },
+        { value: 'report', label: 'report', description: '25-theme dashboard with SEO + liquidity' },
+        { value: 'audit', label: 'audit', description: 'Flag STALE/NO_INVENTORY/THIN themes' },
+        { value: 'overlap', label: 'overlap', description: 'Cross-theme dedupe' },
+        { value: 'show <name>', label: 'show <name>', description: 'Drill into one theme' },
+        { value: 'create <name> --tickers KX-A,KX-B', label: 'create', description: 'Add a new theme' },
+        { value: 'add-series <name> KX-A,KX-B', label: 'add-series', description: 'Map series to a theme' },
+        { value: 'export themes.json', label: 'export', description: 'Save registry to JSON' },
+      ];
+      if (!typed) return opts;
+      return opts.filter(o => o.value.toLowerCase().includes(typed.toLowerCase()));
+    }},
+    { name: 'basket', description: 'Build, backtest, or size diversified baskets', getArgumentCompletions: (typed: string): AutocompleteItem[] | null => {
+      const opts = [
+        { value: 'build', label: 'build', description: 'Diversified basket builder (cluster + correlation caps)' },
+        { value: 'backtest', label: 'backtest', description: 'NAV + Sharpe/MaxDD/WinRate over basket history' },
+        { value: 'size', label: 'size', description: 'Fractional Kelly sizing for picked legs' },
+        { value: 'candles', label: 'candles', description: 'OHLC bars for a weighted basket NAV' },
+        { value: 'validate', label: 'validate', description: 'Sanity-check a proposed basket (corr, clusters, calendar)' },
+        { value: 'build --category crypto --min-volume 10000 -n 8 --max-per-cluster 2 --max-corr 0.6', label: 'build crypto basket', description: 'Build 8-leg crypto basket' },
+        { value: 'backtest --tickers KX-A,KX-B --timeframe 1y', label: 'backtest 1y', description: 'Backtest a basket over 1y' },
+        { value: 'backtest --theme "Iran Escalation" --timeframe 3m', label: 'backtest --theme', description: 'Backtest an editorial theme NAV' },
+        { value: 'candles --theme "Fed Cuts Aggressively" --timeframe 1y', label: 'candles --theme', description: 'NAV candles for a theme' },
+        { value: 'validate --theme "Iran Escalation" --bankroll 1000', label: 'validate --theme', description: 'Sanity-check theme basket' },
+        { value: 'size --auto-probs --theme "AI Race Milestones" --bankroll 1000 --kelly 0.25', label: 'size --auto-probs', description: 'Auto-fetch model edges + Kelly-size' },
+      ];
+      if (!typed) return opts;
+      return opts.filter(o => o.value.toLowerCase().includes(typed.toLowerCase()));
+    }},
     // Utility
     { name: 'help', description: 'Show help (/help <command> for details)', getArgumentCompletions: helpTopicCompletions },
     { name: 'model', description: 'Change LLM model/provider', getArgumentCompletions: usageHint('<provider:model>', 'e.g. anthropic:sonnet') },