export type DashboardLine = {
  key: string;
  label: string;
  color: string;
  yAxisId?: "left" | "right";
};

export type Playbook = {
  whatItMeasures: string;
  interpretation: string[];
  tradeExpressions: string[];
  caveats: string[];
  companionChecks: string[];
};

export type OptionsDashboardConfig = {
  id: string;
  title: string;
  description: string;
  family: string;
  dualAxis?: boolean;
  lines: DashboardLine[];
  tableColumns: string[];
  relatedSignals: string[];
  playbook: Playbook;
};

export const OPTIONS_DASHBOARDS: OptionsDashboardConfig[] = [
  {
    id: "vol_surface",
    title: "Vol Surface",
    description: "Smile slices, ATM term structure, and surface repricing across BTC and ETH.",
    family: "surface",
    lines: [
      { key: "mean_mark_iv", label: "Mean IV", color: "#6ac2ff" },
      { key: "iv_change_24h", label: "IV Δ 24H", color: "#ffd166" },
      { key: "iv_change_7d", label: "IV Δ 7D", color: "#8dd3c7" },
    ],
    tableColumns: [
      "ts",
      "tenor_bucket",
      "moneyness_bucket",
      "mean_mark_iv",
      "iv_change_24h",
      "option_count",
      "quality_flag",
    ],
    relatedSignals: ["btc_vvix", "eth_vvix"],
    playbook: {
      whatItMeasures:
        "This is the base map of the options market: where implied vol sits across tenor and moneyness, and how that map is changing through time.",
      interpretation: [
        "ATM-led repricing usually means the market is moving its baseline uncertainty estimate. Wing-led repricing usually means crash or squeeze insurance is repricing faster than the center of the surface.",
        "If 7D and 14D move sharply while 30D and 60D lag, the market is pricing a near-term catalyst or stress window rather than a durable regime shift.",
        "A smile steepening with flat ATM often points to demand for tails, while parallel shifts across all buckets are broader vol repricings.",
      ],
      tradeExpressions: [
        "Prefer straddles when ATM is repricing the fastest and the move looks regime-wide.",
        "Prefer strangles or wing structures when wing buckets are moving independently of ATM.",
        "If the front end has already repriced hard but the back end has not, look for calendars or tenor spreads rather than outright long vol.",
      ],
      caveats: [
        "Low coverage and poor fit quality can make wing changes look more dramatic than they are.",
        "Single-hour spikes should be checked against positioning and dislocation pages before assuming the whole smile has moved.",
      ],
      companionChecks: [
        "Check Skew / Crash Premium to confirm whether the move is downside-insurance led.",
        "Check Surface Dislocation to see whether the move is regime repricing or local quote distortion.",
      ],
    },
  },
  {
    id: "carry_vrp",
    title: "Carry / VRP",
    description: "Implied versus realized carry, roll-down, and short-gamma richness.",
    family: "carry",
    lines: [
      { key: "carry_spread_7d", label: "Carry 7D", color: "#6ac2ff" },
      { key: "carry_spread_30d", label: "Carry 30D", color: "#ffd166" },
      { key: "carry_zscore", label: "Carry Z", color: "#f58549" },
      { key: "roll_down_carry", label: "Roll-Down", color: "#8dd3c7" },
    ],
    tableColumns: [
      "ts",
      "carry_spread_7d",
      "carry_spread_30d",
      "carry_zscore",
      "roll_down_carry",
      "carry_regime",
      "quality_flag",
    ],
    relatedSignals: ["btc_razor", "eth_razor", "btc_vvix", "eth_vvix"],
    playbook: {
      whatItMeasures:
        "This compares what the market is charging in short-dated implied vol against what the underlying has actually delivered, plus how much carry rolls down across the front of the curve.",
      interpretation: [
        "High positive carry means short-dated premium is rich relative to recent realized movement. That is fertile ground for short-gamma ideas, but only if vol-of-vol is not simultaneously screaming higher.",
        "Cheap or negative carry means the market is no longer paying enough for the risk. That is where long-gamma entries become more attractive, especially after vol compressions.",
        "Roll-down carry shows whether time decay is working with you or against you as the front tenor slides toward expiry.",
      ],
      tradeExpressions: [
        "Short premium when carry is rich, roll-down is favorable, and VVIX is not in a high-stress regime.",
        "Avoid shorting rich carry blindly when VVIX and skew are both expanding; that often means the market is rich for a reason.",
        "Use long gamma when carry has compressed after a prolonged calm and the surface is starting to wake up.",
      ],
      caveats: [
        "Carry can stay rich for longer than expected in stable regimes.",
        "Realized vol based on short history can understate latent event risk.",
      ],
      companionChecks: [
        "Check VVIX to see whether high carry is being offset by high vol-of-vol risk.",
        "Check Razor to see whether seller edge is already exhausted.",
      ],
    },
  },
  {
    id: "skew_crash_premium",
    title: "Skew / Crash Premium",
    description: "Crash insurance demand, skew stress, and skew unwinds.",
    family: "skew",
    lines: [
      { key: "rr_25_7d", label: "RR 25D 7D", color: "#6ac2ff" },
      { key: "rr_25_30d", label: "RR 25D 30D", color: "#ffd166" },
      { key: "skew_slope", label: "Skew Slope", color: "#f58549" },
      { key: "skew_zscore", label: "Skew Z", color: "#8dd3c7" },
    ],
    tableColumns: [
      "ts",
      "rr_25_7d",
      "rr_25_30d",
      "skew_slope",
      "skew_zscore",
      "crash_premium_regime",
      "quality_flag",
    ],
    relatedSignals: ["btc_vvix", "eth_vvix"],
    playbook: {
      whatItMeasures:
        "This tracks how expensive downside insurance is relative to upside and how that premium is evolving across the curve.",
      interpretation: [
        "A more negative short-dated risk reversal means the market is paying up for crash protection.",
        "If the front-end skew gets much more negative than the back end, the market is pricing immediate downside stress rather than a slow regime change.",
        "A fast skew unwind after a panic often marks the first stage of normalization, even before ATM vol fully compresses.",
      ],
      tradeExpressions: [
        "Use skew stress to choose between selling symmetric premium and selling expensive downside tails selectively.",
        "Use skew unwind conditions to step into short-vol structures more carefully after a panic.",
        "When skew is calm but ATM is rising, prefer neutral long-vol structures over tail-specific hedges.",
      ],
      caveats: [
        "Skew can remain steep through clustered downside moves.",
        "Spot direction alone does not explain skew; flow and event risk matter.",
      ],
      companionChecks: [
        "Check Positioning / Flow to see whether the market is crowded around certain downside strikes.",
        "Check Carry / VRP to avoid selling skew into a still-rich stress regime.",
      ],
    },
  },
  {
    id: "surface_dislocation",
    title: "Surface Dislocation",
    description: "Quote-versus-fit residuals and isolated smile anomalies.",
    family: "dislocation",
    lines: [
      { key: "max_residual", label: "Max Residual", color: "#6ac2ff" },
      { key: "mean_abs_residual", label: "Mean Abs Residual", color: "#ffd166" },
      { key: "wing_residual", label: "Wing Residual", color: "#f58549" },
      { key: "dislocation_zscore", label: "Dislocation Z", color: "#8dd3c7" },
    ],
    tableColumns: [
      "ts",
      "tenor_bucket",
      "max_residual",
      "mean_abs_residual",
      "wing_residual",
      "dislocation_zscore",
      "quality_flag",
    ],
    relatedSignals: ["btc_vvix", "eth_vvix"],
    playbook: {
      whatItMeasures:
        "This isolates where actual option quotes diverge from the fitted surface, highlighting local rich/cheap areas rather than broad market repricing.",
      interpretation: [
        "A broad rise in residuals across many tenors usually means the fit is struggling or the whole surface is moving too quickly to summarize with a smooth parameterization.",
        "A concentrated residual in one tenor or wing is more likely to be a tradeable local distortion.",
        "Persistent dislocations matter more than one-off prints.",
      ],
      tradeExpressions: [
        "Use isolated rich wings to look for relative-value sales against cleaner nearby structures.",
        "Use cheap local points to find entry zones for long convexity without paying for the whole surface.",
        "When dislocation is high but carry is neutral, prioritize relative-value trades over outright vol direction.",
      ],
      caveats: [
        "Poor fit quality can manufacture apparent dislocations.",
        "Sparse strikes in a tenor can exaggerate local residuals.",
      ],
      companionChecks: [
        "Check Vol Surface to see whether the residual is local or part of a bigger smile move.",
        "Check Positioning / Flow to see whether concentrated OI is driving the distortion.",
      ],
    },
  },
  {
    id: "cross_asset_rv",
    title: "Cross-Asset Relative Value",
    description: "BTC versus ETH spread monitoring across vol, skew, VVIX, and Razor.",
    family: "relative_value",
    lines: [
      { key: "atm_iv_spread_7d", label: "ATM IV Spread 7D", color: "#6ac2ff" },
      { key: "skew_spread_30d", label: "Skew Spread 30D", color: "#ffd166" },
      { key: "vvix_spread", label: "VVIX Spread", color: "#f58549" },
      { key: "spread_zscore", label: "Spread Z", color: "#8dd3c7" },
    ],
    tableColumns: [
      "ts",
      "pair_id",
      "atm_iv_spread_7d",
      "skew_spread_30d",
      "vvix_spread",
      "spread_zscore",
      "relative_regime",
    ],
    relatedSignals: ["btc_vvix", "eth_vvix", "btc_razor", "eth_razor"],
    playbook: {
      whatItMeasures:
        "This compares BTC and ETH options regimes directly, which is often cleaner than trading outright levels.",
      interpretation: [
        "A positive spread means BTC is richer than ETH on that dimension; a negative spread means the opposite.",
        "Large z-scores mark relative dislocations, not absolute cheapness or richness.",
        "Relative-value works best when both assets share the same broad market regime but diverge in pricing detail.",
      ],
      tradeExpressions: [
        "Use this for pair-style vol expressions when outright exposure feels too regime-sensitive.",
        "Prefer RV setups when both assets are calm or both stressed, but one is materially richer on skew or VVIX.",
        "Use the score as a screening tool, then confirm with the asset-specific surface and carry pages.",
      ],
      caveats: [
        "Asset-specific catalysts can break historical spread relationships quickly.",
        "Relative cheapness does not mean outright cheapness.",
      ],
      companionChecks: [
        "Check each asset’s Carry / VRP page before putting on a pair trade.",
        "Check each asset’s Vol Surface page to see whether the spread is ATM-led or wing-led.",
      ],
    },
  },
  {
    id: "positioning_flow",
    title: "Positioning / Flow",
    description: "Open interest and volume concentration across expiry and moneyness buckets.",
    family: "positioning",
    lines: [
      { key: "open_interest_share", label: "OI Share", color: "#6ac2ff" },
      { key: "volume_share", label: "Volume Share", color: "#ffd166" },
      { key: "atm_pinning_concentration", label: "ATM Pinning", color: "#f58549" },
      { key: "wing_concentration", label: "Wing Concentration", color: "#8dd3c7" },
    ],
    tableColumns: [
      "ts",
      "expiry_bucket",
      "moneyness_bucket",
      "open_interest",
      "open_interest_share",
      "volume_share",
      "quality_flag",
    ],
    relatedSignals: ["btc_razor", "eth_razor"],
    playbook: {
      whatItMeasures:
        "This shows where open interest and trading flow are clustered, which helps explain magnet strikes, crowded tails, and why parts of the smile refuse to normalize.",
      interpretation: [
        "High ATM pinning concentration means the market is crowded around central strikes and expiry behavior can become sticky.",
        "High wing concentration means the market is paying up to warehouse tail risk or hedge it.",
        "Rising volume share without corresponding OI change can mean churn; rising OI share is a stronger positioning signal.",
      ],
      tradeExpressions: [
        "Use pinning concentration to avoid overestimating breakout probability into expiry.",
        "Use crowded wings to avoid leaning the same way as the market without compensation.",
        "Use flow concentration to confirm or reject what skew and dislocation are suggesting.",
      ],
      caveats: [
        "OI is not directional by itself.",
        "Bucketed positioning is a context indicator, not a standalone signal.",
      ],
      companionChecks: [
        "Check Skew / Crash Premium when wing concentration is elevated.",
        "Check Surface Dislocation when localized flow seems to be distorting quotes.",
      ],
    },
  },
  {
    id: "vol_cone",
    title: "Vol Cone",
    description: "Historical percentile context for implied and realized volatility by tenor.",
    family: "cone",
    lines: [
      { key: "implied_percentile", label: "IV Percentile", color: "#6ac2ff" },
      { key: "realized_percentile", label: "RV Percentile", color: "#ffd166" },
      { key: "iv_rv_spread_percentile", label: "IV-RV Spread %ile", color: "#8dd3c7" },
    ],
    tableColumns: ["ts", "tenor", "implied_vol", "realized_vol", "iv_rv_spread_percentile", "quality_flag"],
    relatedSignals: ["btc_vvix", "eth_vvix"],
    playbook: {
      whatItMeasures:
        "This places current implied and realized vol in their own recent historical context so you can tell whether a rich or cheap reading is truly extreme or just normal for the regime.",
      interpretation: [
        "High implied percentile with low realized percentile means the market is charging a lot versus what it has recently delivered.",
        "High implied and high realized percentiles together usually mean a genuinely stressed regime rather than a one-sided overpricing.",
        "A high IV-RV spread percentile is the cleanest signal that carry is historically rich at that tenor.",
      ],
      tradeExpressions: [
        "Use rich cone readings to tighten your filter for short premium setups instead of shorting every high absolute IV print.",
        "Use low cone readings after compression to identify where long gamma is no longer obviously overpriced.",
      ],
      caveats: [
        "The cone is historical, not structural; a new regime can reset what counts as rich or cheap.",
        "Short histories make percentile ranks unstable.",
      ],
      companionChecks: [
        "Check Carry / VRP to see whether the rich/cheap reading is also showing up in the direct carry spread.",
        "Check Funding Context when vol looks rich but basis positioning is also stretched.",
      ],
    },
  },
  {
    id: "term_structure_momentum",
    title: "Term Structure Momentum",
    description: "24h and 72h changes in front-to-back term slope.",
    family: "term",
    lines: [
      { key: "term_slope_7_30", label: "Slope 7D-30D", color: "#6ac2ff" },
      { key: "term_slope_change_24h", label: "Slope Δ 24H", color: "#ffd166" },
      { key: "term_slope_change_72h", label: "Slope Δ 72H", color: "#8dd3c7" },
    ],
    tableColumns: ["ts", "term_slope_7_30", "term_slope_change_24h", "term_slope_change_72h", "momentum_regime", "quality_flag"],
    relatedSignals: ["btc_vvix", "eth_vvix"],
    playbook: {
      whatItMeasures:
        "This shows whether front-end vol is steepening or flattening versus the back of the curve, which is the timing layer for calendar and tenor-spread trades.",
      interpretation: [
        "Positive short-horizon slope change means front-end pressure is building faster than the back end.",
        "Negative slope change means near-term fear is decaying or being pushed further out.",
      ],
      tradeExpressions: [
        "Use steepening to prefer front-vs-back long gamma or defensive calendars.",
        "Use flattening after a spike to look for normalization in calendars rather than outright short vol immediately.",
      ],
      caveats: [
        "Term structure moves can be event-driven and fade abruptly once the catalyst passes.",
      ],
      companionChecks: [
        "Check Vol Surface for whether the shift is ATM-led or wing-led.",
        "Check Vol Regime Transitions before treating one slope change as a durable regime shift.",
      ],
    },
  },
  {
    id: "gamma_exposure",
    title: "Gamma Exposure",
    description: "True gamma concentration and pinning pressure by expiry and strike bucket.",
    family: "gamma",
    lines: [
      { key: "gamma_exposure", label: "Gamma Exposure", color: "#6ac2ff" },
      { key: "gamma_share", label: "Gamma Share", color: "#ffd166" },
      { key: "pinning_concentration", label: "Pinning", color: "#8dd3c7" },
    ],
    tableColumns: ["ts", "expiry_bucket", "strike_bucket", "gamma_exposure", "gamma_share", "pinning_concentration", "quality_flag"],
    relatedSignals: ["btc_razor", "eth_razor"],
    playbook: {
      whatItMeasures:
        "This aggregates actual option gamma into expiry and strike buckets so you can see where dealer hedging pressure is most likely to pin or amplify spot.",
      interpretation: [
        "High ATM pinning concentration usually supports sticky expiry behavior and mean reversion around crowded strikes.",
        "Large wing gamma pockets suggest the market is warehousing convexity away from spot and can react sharply if those zones are tested.",
      ],
      tradeExpressions: [
        "Reduce breakout conviction near strong pinning zones into expiry.",
        "Use extreme wing gamma pockets to frame where tail demand is concentrated before selling or buying convexity.",
      ],
      caveats: [
        "This is still a market structure view, not a full dealer-position model.",
      ],
      companionChecks: [
        "Check Positioning / Flow for open-interest confirmation.",
        "Check Surface Dislocation for whether concentrated gamma is also distorting quotes locally.",
      ],
    },
  },
  {
    id: "funding_context",
    title: "Funding Context",
    description: "Perpetual funding extremes and their interaction with the current vol regime.",
    family: "funding",
    dualAxis: true,
    lines: [
      { key: "funding_rate", label: "Funding", color: "#6ac2ff", yAxisId: "left" },
      { key: "funding_change_24h", label: "Funding Δ 24H", color: "#8dd3c7", yAxisId: "left" },
      { key: "funding_rate_zscore", label: "Funding Z", color: "#ffd166", yAxisId: "right" },
    ],
    tableColumns: ["ts", "funding_rate", "funding_rate_zscore", "funding_change_24h", "funding_regime", "quality_flag"],
    relatedSignals: ["btc_vvix", "eth_vvix", "btc_razor", "eth_razor"],
    playbook: {
      whatItMeasures:
        "This puts perp basis pressure next to the vol regime so you can tell whether crowded directional positioning is reinforcing or fading the options setup.",
      interpretation: [
        "Very positive funding usually means crowded longs; very negative funding usually means crowded shorts.",
        "Extreme funding with rising qVVIX is more dangerous than extreme funding in a quiet vol regime.",
      ],
      tradeExpressions: [
        "Use stretched funding plus elevated vol-of-vol as a warning against blindly harvesting carry.",
        "Use neutralizing funding after an extreme as confirmation that the crowded directional leg is unwinding.",
      ],
      caveats: [
        "Funding can remain extreme longer than expected during trend regimes.",
      ],
      companionChecks: [
        "Check Carry / VRP before translating funding extremes into short-vol trades.",
        "Check Vol Regime Transitions to see whether the regime is actually turning or just noisy.",
      ],
    },
  },
  {
    id: "straddle_breakeven",
    title: "Straddle Breakeven",
    description: "ATM 7D breakeven move versus realized move to explain gamma richness or cheapness.",
    family: "breakeven",
    lines: [
      { key: "breakeven_move_pct", label: "Breakeven %", color: "#6ac2ff" },
      { key: "realized_move_7d_pct", label: "Realized Move %", color: "#ffd166" },
      { key: "breakeven_gap_pct", label: "Gap %", color: "#8dd3c7" },
    ],
    tableColumns: ["ts", "breakeven_move_pct", "realized_move_7d_pct", "breakeven_gap_pct", "breakeven_regime", "quality_flag"],
    relatedSignals: ["btc_razor", "eth_razor"],
    playbook: {
      whatItMeasures:
        "This compares what a fresh ATM 7D straddle needs to move to break even against what the underlying has actually been doing.",
      interpretation: [
        "A positive gap means realized movement is outrunning breakeven and gamma has been too cheap.",
        "A negative gap means realized movement is undershooting breakeven and gamma has been too rich.",
      ],
      tradeExpressions: [
        "Use a persistently negative gap to explain seller edge on Razor and filter short-gamma ideas.",
        "Use a positive gap after compression to justify long-gamma entries even if absolute IV still looks high.",
      ],
      caveats: [
        "This is a coarse monitor of realized movement, not a full path-dependent straddle PnL model.",
      ],
      companionChecks: [
        "Check Razor for whether the cumulative long-vs-short gamma ledger agrees.",
        "Check Vol Cone to see whether the breakeven gap is also historically extreme.",
      ],
    },
  },
  {
    id: "vol_regime_transitions",
    title: "Vol Regime Transitions",
    description: "Empirical transition probabilities and state-duration statistics for the current vol regime.",
    family: "transitions",
    lines: [
      { key: "next_state_probability_long_vol_bias", label: "P(next long vol)", color: "#6ac2ff" },
      { key: "next_state_probability_neutral", label: "P(next neutral)", color: "#ffd166" },
      { key: "median_state_duration_hours", label: "Median Duration", color: "#8dd3c7" },
    ],
    tableColumns: ["ts", "signal_state", "prior_state", "next_state_probability_long_vol_bias", "next_state_probability_neutral", "median_state_duration_hours", "quality_flag"],
    relatedSignals: ["btc_vvix", "eth_vvix", "btc_razor", "eth_razor"],
    playbook: {
      whatItMeasures:
        "This summarizes how sticky the current vol regime has historically been and what state tends to follow next.",
      interpretation: [
        "High persistence means the current regime tends to last; low persistence means the state is noisy and quick to mean revert.",
        "Transition probabilities are base rates, not forecasts, but they matter for sizing and time stops.",
      ],
      tradeExpressions: [
        "Use persistent long-vol regimes to give long-gamma trades more room.",
        "Use low persistence to shrink conviction on regime-based carry trades.",
      ],
      caveats: [
        "Short live history makes transition estimates unstable early on.",
      ],
      companionChecks: [
        "Check Funding Context for whether positioning supports the current regime.",
        "Check Term Structure Momentum for whether the regime is accelerating or fading.",
      ],
    },
  },
  {
    id: "surface_factor_rv",
    title: "Surface Factor RV",
    description: "Latent surface-factor momentum and residual node value across normalized surface cells.",
    family: "alpha_canvas",
    lines: [
      { key: "factor_momentum_24h", label: "Factor Mom 24H", color: "#6ac2ff" },
      { key: "node_residual_zscore", label: "Residual Z", color: "#ffd166" },
      { key: "residual_value_score", label: "RV Score", color: "#8dd3c7" },
    ],
    tableColumns: ["ts", "tenor_bucket", "moneyness_bucket", "factor_momentum_24h", "node_residual_zscore", "residual_value_score", "quality_flag"],
    relatedSignals: ["surface_factor_score", "residual_surface_rv_score", "btc_vvix", "eth_vvix"],
    playbook: {
      whatItMeasures:
        "This separates common surface repricing from local rich and cheap nodes, which is the direct translation of factor momentum and residual relative value into crypto options.",
      interpretation: [
        "Positive factor momentum means the common surface factor is still repricing in one direction rather than mean reverting.",
        "Large negative residual z-scores can point to locally cheap nodes after controlling for the broader surface move.",
        "Liquidity weighting matters because thin nodes can look statistically cheap without being practically tradeable.",
      ],
      tradeExpressions: [
        "Use factor momentum for surface-following calendar or wing baskets when the common repricing is broad.",
        "Use residual value for relative-value fades when the local node is extreme but the factor backdrop is stable.",
      ],
      caveats: [
        "Sparse strikes or poor fit quality can create fake residuals.",
        "This is a research ranking layer, not a direct trade blotter.",
      ],
      companionChecks: [
        "Check Surface Dislocation for fit stress.",
        "Check Positioning / Flow for local OI concentration before fading a residual.",
      ],
    },
  },
  {
    id: "ml_carry_toxicity",
    title: "ML Carry Toxicity",
    description: "Cost-adjusted carry with jump, flow toxicity, spread, and hedge-cost vetoes.",
    family: "alpha_canvas",
    dualAxis: true,
    lines: [
      { key: "gross_carry_score", label: "Gross Carry", color: "#6ac2ff", yAxisId: "left" },
      { key: "net_carry_score", label: "Net Carry", color: "#ffd166", yAxisId: "left" },
      { key: "toxicity_score", label: "Toxicity", color: "#f58549", yAxisId: "right" },
      { key: "carry_confidence", label: "Confidence", color: "#8dd3c7", yAxisId: "right" },
    ],
    tableColumns: ["ts", "forecast_rv_7d", "gross_carry_score", "net_carry_score", "toxicity_score", "carry_veto", "quality_flag"],
    relatedSignals: ["ml_carry_toxicity_score", "vol_carry_score", "toxicity_score"],
    playbook: {
      whatItMeasures:
        "This is the document’s IV minus forecast-RV carry engine after subtracting the parts that usually kill crypto short-vol trades: jump risk, toxic flow, hedge bleed, spread cost, and funding drag.",
      interpretation: [
        "A large gap between gross and net carry means the raw carry view is being cancelled by implementation risk.",
        "Carry vetoes matter more than headline carry level when the tape is turning informational or jumpy.",
      ],
      tradeExpressions: [
        "Only lean on short-vol carry when net carry stays positive and confidence is stable.",
        "Use carry veto states as a hard filter rather than a soft warning.",
      ],
      caveats: [
        "This is still a heuristic forecast stack, not a trained production model.",
      ],
      companionChecks: [
        "Check Order Flow Toxicity and Funding-Basis Carry on the perps side.",
        "Check Adaptive Hedging before trusting a net carry edge.",
      ],
    },
  },
  {
    id: "expiry_flow_map",
    title: "Expiry Flow Map",
    description: "Pain strike, dominant strike concentration, gamma, vanna, charm, and pin-versus-breakout state.",
    family: "alpha_canvas",
    lines: [
      { key: "pinning_score", label: "Pinning", color: "#6ac2ff" },
      { key: "breakout_score", label: "Breakout", color: "#ffd166" },
      { key: "distance_to_pain_pct", label: "Dist to Pain", color: "#f58549" },
      { key: "local_oi_concentration", label: "OI Conc", color: "#8dd3c7" },
    ],
    tableColumns: ["ts", "expiry_bucket", "strike_bucket", "pain_strike", "dominant_strike", "pinning_score", "flow_regime"],
    relatedSignals: ["expiry_pin_score", "gamma_flip_score", "btc_razor", "eth_razor"],
    playbook: {
      whatItMeasures:
        "This is the dealer-flow map from the research doc: where expiry magnets are strongest and where gamma, vanna, and charm are more likely to amplify rather than damp spot.",
      interpretation: [
        "Positive-gamma pin states support mean reversion toward dominant strikes.",
        "High breakout scores with distance from pain suggest dealer hedging may amplify the move instead of pinning it.",
      ],
      tradeExpressions: [
        "Fade toward pain only in positive-gamma pin states with low breakout pressure.",
        "Respect momentum when breakout pressure dominates and spot is pulling away from pain.",
      ],
      caveats: [
        "Without true option trade sign, this remains inferred dealer-flow context.",
        "Missing greeks now surface as partial context rather than being silently treated as zero exposure.",
      ],
      companionChecks: [
        "Check Positioning / Flow for strike crowding confirmation.",
        "Check Depth Resilience to tell whether the underlying can absorb hedging flow.",
      ],
    },
  },
  {
    id: "adaptive_hedging",
    title: "Adaptive Hedging",
    description: "Smile-aware delta, minimum-variance overlay, no-trade bands, and route preference.",
    family: "alpha_canvas",
    dualAxis: true,
    lines: [
      { key: "smile_aware_delta", label: "Smile Delta", color: "#6ac2ff", yAxisId: "left" },
      { key: "min_var_delta", label: "Min-Var Delta", color: "#ffd166", yAxisId: "left" },
      { key: "hedge_band_width", label: "Band Width", color: "#f58549", yAxisId: "right" },
      { key: "route_score", label: "Route Score", color: "#8dd3c7", yAxisId: "right" },
    ],
    tableColumns: ["ts", "smile_aware_delta", "min_var_delta", "hedge_band_width", "expected_hedge_bleed_bps", "route_preference", "quality_flag"],
    relatedSignals: ["adaptive_hedge_score", "ml_carry_toxicity_score", "fragility_score"],
    playbook: {
      whatItMeasures:
        "This converts the hedge-aware execution section into a research overlay: how much to adjust naive delta, how wide the no-trade band should be, and whether perp or future routing is cleaner.",
      interpretation: [
        "Wide bands mean over-hedging is likely to destroy edge faster than residual delta risk.",
        "A weak route score means the market is expensive to hedge even if the vol view itself is right.",
      ],
      tradeExpressions: [
        "Use this to decide whether a vol trade should be actively hedged, lightly hedged, or left alone.",
        "Treat route preference as implementation guidance, not an execution instruction.",
      ],
      caveats: [
        "This is a research overlay only. No live hedge engine is being built here.",
      ],
      companionChecks: [
        "Check ML Carry Toxicity for edge after cost.",
        "Check Funding-Basis Skew for route contamination from crowded basis pressure.",
      ],
    },
  },
  {
    id: "sessionality_clocks",
    title: "Sessionality Clocks",
    description: "Asia, Europe, US, weekend, funding-window, and expiry-window vol/carry behavior.",
    family: "alpha_canvas",
    lines: [
      { key: "session_realized_vol", label: "Session RV", color: "#6ac2ff" },
      { key: "session_implied_vol", label: "Session IV", color: "#ffd166" },
      { key: "session_carry", label: "Session Carry", color: "#f58549" },
      { key: "sessionality_score", label: "Session Score", color: "#8dd3c7" },
    ],
    tableColumns: ["ts", "session_bucket", "session_realized_vol", "session_carry", "carry_switch", "quality_flag"],
    relatedSignals: ["sessionality_score", "vol_regime_score", "toxicity_score"],
    playbook: {
      whatItMeasures:
        "This remaps the day-versus-night and seasonality literature into crypto’s actual clock: UTC sessions, weekend effects, funding timestamps, and expiry windows.",
      interpretation: [
        "Not all high-vol hours are equal. Some are event clocks, some are flow clocks, and some are just low-liquidity noise.",
        "Funding and expiry windows often matter more than broad session labels on their own.",
      ],
      tradeExpressions: [
        "Use sessionality to time when carry should be on, reduced, or fully vetoed.",
        "Use funding and expiry windows as timing filters around otherwise valid setups.",
      ],
      caveats: [
        "Clock effects drift over time and should be treated as context, not law.",
      ],
      companionChecks: [
        "Check ML Carry Toxicity for implementation risk.",
        "Check Expiry Flow Map near expiry-sensitive windows.",
      ],
    },
  },
  {
    id: "btc_eth_dispersion",
    title: "BTC-ETH Dispersion",
    description: "Surface-implied correlation proxy gap, realized correlation forecast, and cross-smile consistency.",
    family: "alpha_canvas",
    lines: [
      { key: "implied_correlation", label: "Impl Corr Proxy", color: "#6ac2ff" },
      { key: "realized_corr_forecast", label: "RV Corr Fcst", color: "#ffd166" },
      { key: "corr_gap", label: "Corr Gap", color: "#f58549" },
      { key: "dispersion_score", label: "Dispersion", color: "#8dd3c7" },
    ],
    tableColumns: ["ts", "tenor", "implied_correlation", "realized_corr_forecast", "corr_gap", "dispersion_regime", "quality_flag"],
    relatedSignals: ["dispersion_score", "cross_asset_vol_score", "btc_vvix", "eth_vvix"],
    playbook: {
      whatItMeasures:
        "This translates the FX correlation and dispersion papers into BTC-ETH by comparing a matched-tenor surface-implied correlation proxy against a realized-correlation forecast and smile consistency.",
      interpretation: [
        "A positive correlation gap means the surface-implied correlation proxy is richer than the forecast and supports long-dispersion thinking.",
        "Smile inconsistency lowers confidence because the relative-value signal may actually be a skew problem.",
      ],
      tradeExpressions: [
        "Use this as the pair-trade layer when outright vol is too regime-sensitive.",
        "Require aligned tenor coverage and clean smile consistency before trusting a dispersion signal.",
      ],
      caveats: [
        "This is synthetic dispersion research built from matched BTC and ETH inputs, not an index/constituent options book.",
        "The correlation input is a surface-implied proxy from matched ATM IV co-moves, not a listed basket-option implied correlation.",
      ],
      companionChecks: [
        "Check Cross-Asset Relative Value for simpler spread context.",
        "Check Surface Factor RV for whether the spread is factor-led or local.",
      ],
    },
  },
  {
    id: "funding_basis_skew",
    title: "Funding-Basis Skew",
    description: "Funding and basis extremes mapped into RR/BF richness and skew regime.",
    family: "alpha_canvas",
    dualAxis: true,
    lines: [
      { key: "basis_pressure", label: "Basis Pressure", color: "#6ac2ff", yAxisId: "left" },
      { key: "skew_richness", label: "Skew Richness", color: "#ffd166", yAxisId: "left" },
      { key: "funding_basis_skew_score", label: "FB x Skew", color: "#f58549", yAxisId: "right" },
      { key: "funding_rate_zscore", label: "Funding Z", color: "#8dd3c7", yAxisId: "right" },
    ],
    tableColumns: ["ts", "basis_bps", "funding_rate", "skew_richness", "funding_basis_skew_score", "regime", "quality_flag"],
    relatedSignals: ["funding_skew_score", "funding_vol_context_score", "skew_stress_score"],
    playbook: {
      whatItMeasures:
        "This is the funding-basis x skew interaction layer from the document: when crowded basis positioning should change how you read RR and BF richness.",
      interpretation: [
        "Large positive scores usually mean crowded downside-rich conditions rather than clean short-vol carry.",
        "Negative scores can point to call-rich or upside-squeeze conditions where the skew map is telling a different story than ATM.",
      ],
      tradeExpressions: [
        "Use this to choose between symmetric premium, downside-rich, and upside-rich expressions.",
        "Treat basis and skew together when crowded directional positioning is clearly contaminating smile prices.",
      ],
      caveats: [
        "Funding and basis can dominate the read during exchange-specific stress.",
      ],
      companionChecks: [
        "Check Funding Context for the broader regime.",
        "Check Skew / Crash Premium to see whether the score is front-end or curve-wide.",
      ],
    },
  },
];

export const OPTIONS_SIGNAL_DESCRIPTIONS: Record<string, string> = {
  vol_carry_score:
    "Positive values indicate rich short-dated carry and better short-vol carry conditions. Negative values indicate carry compression and better long-gamma conditions.",
  skew_stress_score:
    "Positive values indicate elevated crash-premium pressure and more stressed skew. Negative values indicate skew normalization.",
  surface_dislocation_score:
    "Positive values indicate larger localized quote-versus-fit distortions and better relative-value hunting conditions.",
  cross_asset_vol_score:
    "Positive values indicate BTC is rich versus ETH on the current spread basket; negative values indicate ETH is richer.",
  vol_regime_score:
    "Positive values indicate a more defensive long-vol regime. Negative values indicate a calmer short-vol regime.",
  funding_vol_context_score:
    "Positive values indicate funding is stretched in the same direction as an unstable vol regime, increasing caution on carry trades.",
  breakeven_gap_score:
    "Positive values indicate realized movement is running ahead of short-dated breakevens. Negative values indicate gamma is still being overpaid for.",
  term_structure_momentum_score:
    "Positive values indicate front-end pressure is accelerating faster than the back end. Negative values indicate the front is relaxing.",
  surface_factor_score:
    "Positive values indicate broad surface-factor momentum is strengthening. Negative values indicate the common surface move is fading or reversing.",
  residual_surface_rv_score:
    "Positive values indicate locally cheap nodes after controlling for common surface-factor moves. Negative values indicate locally rich nodes.",
  ml_carry_toxicity_score:
    "Positive values indicate carry remains attractive after jump, toxicity, spread, and hedge-cost penalties. Negative values indicate the carry edge is implementation-dominated.",
  expiry_pin_score:
    "Positive values indicate stronger positive-gamma pinning pressure around dominant strikes into expiry.",
  gamma_flip_score:
    "Positive values indicate higher breakout risk from negative gamma, distance from pain, and unstable expiry flow.",
  adaptive_hedge_score:
    "Positive values indicate cleaner hedge implementation with tighter expected bleed and better route economics.",
  sessionality_score:
    "Positive values indicate the current session and clock context is supportive for the active vol regime; negative values indicate a poor clock for the setup.",
  dispersion_score:
    "Positive values indicate the surface-implied correlation proxy looks rich versus realized-correlation forecast and supports long-dispersion framing. Negative values indicate the opposite.",
  funding_skew_score:
    "Positive values indicate funding and basis pressure are reinforcing downside-rich skew conditions. Negative values indicate call-rich or squeeze-prone skew conditions.",
};
