@pgnio/helios-mcp 0.0.0-stage → 0.2.1

package/docs/ai-agent-indicators/volume_change_point.txt

@@ -0,0 +1,151 @@
+================================================================================
+INDICATOR: VOLUME_CHANGE_POINT — BAYESIAN VOLUME REGIME CHANGE PROBABILITY
+================================================================================
+id:                 volume_change_point
+data_field:         indicators.volatility_clustering.change_point_probability
+                    # NOT a standalone field — embedded in volatility_clustering output
+type:               NUMERIC
+range:              [0.0, 1.0]
+precision:          3 decimal places
+update_rate:        per_tick
+latency_profile:    LAGGING (uses Bayesian Online Changepoint Detection over 60 max run length)
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+IMPORTANT: volume_change_point is not a standalone indicator. It is the
+changePointProbability sub-field of the volatility_clustering output object.
+
+Access path: indicators.volatility_clustering.change_point_probability
+
+Computation: BOCPD (Bayesian Online Changepoint Detection)
+  - Input: sequence of log(volume) values, one per tick
+  - Model: Gaussian distribution with unknown mean and variance per run segment
+  - Hazard rate (prior probability of changepoint at any tick):
+      hazardPrior = 1/60  (prior: changepoints expected roughly every 60 ticks)
+  - Maximum run length tracked: 60 ticks
+  - At each tick, the algorithm maintains probability distributions over all
+    possible run lengths (0 to max_run). It updates these probabilities with
+    the new observed log-volume using Bayesian Gaussian likelihood.
+  - changePointProbability = P(a changepoint occurred at this tick)
+    = marginalized probability that the current run length is 0 or very short.
+
+Interpretation: This indicator answers "Has the volume regime just shifted?"
+High probability means the current volume level is inconsistent with the
+volume pattern from the past N ticks and is likely a new regime.
+
+--------------------------------------------------------------------------------
+RANGE INTERPRETATION
+--------------------------------------------------------------------------------
+  value > 0.7
+    Strong evidence of a volume regime change at this tick. The volume level
+    is inconsistent with the recent run and is likely a new distributional
+    regime. This could be:
+      - Volume surging (breakout initiation, news, large order)
+      - Volume collapsing (end of a high-volume period)
+    Direction of the shift must be determined by comparing current activity
+    to prior activity_ratio or volatility_clustering levels.
+
+  value >= 0.5 AND value <= 0.7
+    Moderate evidence of a regime shift. Volume behavior is inconsistent
+    with the recent pattern but the signal is not definitive yet.
+    Monitor for next few ticks to confirm or deny.
+
+  value < 0.3
+    Low probability of a regime change. Volume is behaving consistently
+    with the recent run. No shift detected.
+
+  value ≈ 0.0
+    Baseline state. No evidence of a changepoint. Volume is in a stable
+    and consistent regime.
+
+NOTE: The hazard prior of 1/60 means the algorithm expects a changepoint roughly
+every 60 ticks on average. The algorithm will correctly produce P ≈ 0.017 at
+every tick when volume is truly stable. Values meaningfully above 0.1 are already
+notable; above 0.5 is a significant detection.
+
+--------------------------------------------------------------------------------
+COMMON SCENARIOS WHERE CHANGE POINT FIRES
+--------------------------------------------------------------------------------
+  SCENARIO A: Volume explosion during consolidation
+    squeeze_energy > 10 (squeeze building)
+    AND change_point_probability > 0.5
+    → Volume is shifting regime during a squeeze. Classic pre-breakout signal.
+       The squeeze energy is about to release.
+
+  SCENARIO B: Volume collapse after a spike
+    Prior activity_ratio was ACTIVE (>= 1.0)
+    AND change_point_probability > 0.6
+    AND current activity_ratio drops to MODERATE
+    → The high-volume phase is ending. Momentum from the prior surge may fade.
+
+  SCENARIO C: Sudden volume shock
+    No prior squeeze building
+    AND change_point_probability > 0.75 in one tick
+    → Sudden volume regime shift not preceded by buildup. Could be news,
+       large liquidation, or unusual market event. Treat as alert for
+       position risk management rather than a directional signal.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.volatility_clustering | CONTAINER
+    change_point_probability is the secondary output of the same computation
+    that provides volatility_clustering multiplier.
+    Read both together: clustering tells you current volume level relative
+    to history; change_point indicates whether that level has SHIFTED.
+
+    IF volatility_clustering >= 1.2 AND change_point_probability > 0.5
+      → Not only is volume elevated, but the elevation is a NEW regime.
+         This combination is stronger than either alone.
+
+  indicators.squeeze_energy | ALERT PAIR
+    IF squeeze_energy > 5 AND change_point_probability > 0.5
+      → Compressed market with a volume regime shift. Highest-priority
+         breakout alerting condition.
+
+  indicators.activity_ratio | CONTEXT
+    change_point_probability does not tell you whether the regime shifted
+    to more or less volume. Use activity_ratio.active and activity_ratio
+    thresholds to determine direction of the volume shift.
+
+  indicators.market_structure | CONTEXT
+    If market_structure transitions to BREAKING_UP or CONFIRMED_BREAK_UP
+    simultaneously with change_point_probability > 0.5, the breakout has
+    both structural and volume regime confirmation.
+
+  indicators.hmi_velocity | COMPANION
+    If a volume regime shift occurs AND hmi_velocity is strongly positive,
+    it suggests the new volume regime is supporting a directional move,
+    not just noise.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Read volatility_clustering.change_point_probability.
+  2  If above 0.5: check activity_ratio to determine if volume is rising or falling.
+  3  If above 0.5: check squeeze_energy for pre-existing compression.
+  4  If above 0.5: check market_structure for structural breakout context.
+  5  Highest-confidence breakout condition: squeeze_energy + change_point_probability + market_structure all elevated.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF market is in first 60 ticks since startup or data reset
+    → BOCPD run-length model requires warmup. Probabilities will be
+       unreliable until 60-tick window has filled.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF change_point_probability > 0.5 is used as a directional signal
+    → INCORRECT. BOCPD detects WHEN a regime shift occurred, not the
+       direction of the shift. A volume changepoint can be a surge OR
+       a collapse. Use activity_ratio to determine which direction.
+
+  IF this indicator is treated as a standalone indicator accessible at a
+  top-level data path
+    → ACCESS PATTERN ERROR. This field is embedded within the
+       volatility_clustering output object. Access via:
+       indicators.volatility_clustering.change_point_probability
+       There is no standalone "indicators.volume_change_point" field.

package/docs/ai-agent-indicators/vwap.txt

@@ -0,0 +1,133 @@
+================================================================================
+INDICATOR: VWAP — VOLUME WEIGHTED AVERAGE PRICE
+================================================================================
+id:                 vwap
+data_field:         indicators.vwap
+type:               PRICE LEVEL (same units as current price)
+range:              Positive real number; tracks price closely
+precision:          Asset tick size
+update_rate:        per_tick (recalculates with each new 1m candle)
+latency_profile:    SLOW — computed from rolling 7-day 1m candle history
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+VWAP is the volume-weighted average of the typical price over all available
+1-minute candles (approximately 7 days, ~10,080 candles).
+
+For each candle:
+  typicalPrice = (high + low + close) / 3
+
+Cumulative computation:
+  cumulativeTPV = Σ(typicalPrice × volume)   over all candles
+  cumulativeVol = Σ(volume)                  over all candles
+  vwap         = cumulativeTPV / cumulativeVol
+
+Also computed from the same pass (for use in vwap_zscore):
+  variance = (Σ(typicalPrice² × volume) / totalVol) - vwap²
+  stdDev   = sqrt(max(variance, 0))
+
+Additional outputs from the same VWAP computation:
+  indicators.vwap_upper_band_1 = vwap + 1 × stdDev
+  indicators.vwap_lower_band_1 = vwap - 1 × stdDev
+  indicators.vwap_upper_band_2 = vwap + 2 × stdDev
+  indicators.vwap_lower_band_2 = vwap - 2 × stdDev
+
+vwap represents the AVERAGE COST of all participants (weighted by volume)
+over the rolling 7-day window. It serves as an anchor price level reflecting
+institutional cost basis. Price trading above VWAP indicates current buyers
+are paying above the average historical cost. Below VWAP indicates buyers
+have an advantage relative to recent average cost.
+
+--------------------------------------------------------------------------------
+INTERPRETATION: VWAP AS A PRICE LEVEL
+--------------------------------------------------------------------------------
+  price > vwap
+    Current price above the 7-day volume-weighted average. Short-term price
+    action is at a premium to the rolling cost basis. Often a sign of bullish
+    positioning but also means buyers are paying above average costs.
+
+  price ≈ vwap (within 0.3% or one standard deviation)
+    Price is at or near the volume-weighted cost basis. This level acts as a
+    fair value anchor. Significant trading activity tends to occur near VWAP.
+
+  price < vwap
+    Current price below the 7-day volume-weighted average. Price is at a
+    discount relative to rolling cost basis. May reflect capitulation or
+    bearish positioning.
+
+  price > vwap_upper_band_2
+    Price is more than 2 standard deviations above VWAP. Historically extended
+    relative to volume-weighted activity. Check vwap_zscore for numeric
+    deviation and bayesian_overbought for RSI context.
+
+  price < vwap_lower_band_2
+    Price is more than 2 standard deviations below VWAP. Historically extended
+    below volume-weighted activity. Potential mean-reversion zone.
+
+--------------------------------------------------------------------------------
+IMPORTANT NOTES ON VWAP AT 7-DAY WINDOW
+--------------------------------------------------------------------------------
+# vwap here is NOT a session VWAP (intraday only). It uses 7 days of data.
+# This makes it a medium-term cost basis, not an intraday anchor.
+# Differences from traditional session VWAP:
+#   - Reacts slowly to price moves (large denominator from 7 days)
+#   - Represents multi-day positioning cost, not single-session cost
+#   - Standard deviation bands are wider due to multi-day price range
+#   - Best used for identifying price extensions vs medium-term fair value
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.vwap_zscore | REQUIRED_COMPANION
+    vwap alone tells you the level; vwap_zscore tells you how far price
+    has deviated in statistical terms. Read vwap_zscore alongside vwap.
+
+  indicators.poc | CONTEXT
+    VWAP (time-volume weighted average) and POC (highest-volume price level)
+    are both volume-anchored references but can diverge during trending periods.
+    IF vwap significantly above POC: multi-day cost basis above the highest-
+      activity price level — area between is a high-significance range.
+    IF price is between vwap and POC: in the strongest support/resistance zone.
+
+  indicators.support / indicators.resistance | CONTEXT
+    Support levels that coincide with VWAP carry higher significance.
+    If price tests VWAP from above and it aligns with a strong support
+    level, both computations independently support the same level.
+
+  indicators.hurst_exponent | COMPANION FOR MEAN-REVERSION
+    IF hurst < 0.4 AND price > vwap_upper_band_2
+      → Statistical mean-reversion tendency PLUS price extended above VWAP.
+         Two independent factors suggest reversion toward VWAP.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Compare current price to vwap level.
+  2  Compare to ±1σ and ±2σ bands.
+  3  Read vwap_zscore for standardized deviation.
+  4  Note alignment with support/resistance and POC levels.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF no 1m candle history is available
+    → VWAP cannot be computed. Treat as unavailable on market open or
+       after a data gap.
+
+  IF volume data has gaps (some candles have zero volume)
+    → VWAP may be skewed. The internal computation handles zero-volume
+       candles but extended gaps reduce reliability.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF using vwap as an intraday fairness anchor only
+    → SCOPE MISMATCH. This VWAP is 7 days. Single-session fair value
+       may differ significantly from this VWAP, especially after large
+       gap opens or multi-day trend moves.
+
+  IF VWAP crossover is used as a trade signal
+    → VWAP is a reference level, not a momentum indicator. Crossovers on a
+       7-day VWAP are not meaningful as short-term entry signals.
+       Use regime or MACD for directional signals.

package/docs/ai-agent-indicators/vwap_zscore.txt

@@ -0,0 +1,154 @@
+================================================================================
+INDICATOR: VWAP_ZSCORE — VWAP Z-SCORE
+================================================================================
+id:                 vwap_zscore
+data_field:         indicators.vwap_zscore
+type:               NUMERIC
+range:              Unbounded; typical practical range -4.0 to +4.0
+precision:          3 decimal places
+update_rate:        per_tick
+latency_profile:    SLOW (inherits VWAP's 7-day window sluggishness)
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+vwap_zscore expresses how many standard deviations the current price is from
+the 7-day VWAP.
+
+Formula:
+  vwap_zscore = (currentPrice - vwap) / stdDev
+
+Where stdDev is computed from the same 7-day candle history:
+  variance = (Σ(typicalPrice² × volume) / totalVol) - vwap²
+  stdDev   = sqrt(max(variance, 0))
+
+This is a volume-weighted standard deviation, not a simple price standard
+deviation. It weights the dispersion more heavily toward price levels that
+traded with more volume.
+
+Threshold modulation by volatility_clustering:
+  The standard thresholds (below) are internally scaled by volcMultiplier,
+  where volcMultiplier is clamped from indicators.volatility_clustering
+  (range 0.6-2.0 based on that indicator's output).
+  
+  In high-volatility-clustering conditions, the band thresholds expand,
+  meaning larger deviations are required to reach the same "extreme" label.
+  In low-volatility conditions, thresholds compress.
+
+Base thresholds (before volatility scaling):
+  > +2.0  →  FAR_ABOVE
+  +0.5 to +2.0  →  ABOVE
+  -0.5 to +0.5  →  AT_VWAP
+  -2.0 to -0.5  →  BELOW
+  < -2.0  →  FAR_BELOW
+
+--------------------------------------------------------------------------------
+RANGE INTERPRETATION
+--------------------------------------------------------------------------------
+  value > 2.0
+    Price is significantly above the 7-day volume-weighted cost basis —
+    more than 2 standard deviations above VWAP. This level is historically
+    rare during the 7-day window. Associated with extended bullish states or
+    momentum breakouts. Mean-reversion risk is elevated when other momentum
+    indicators also show fatigue.
+
+  value >= 0.5 AND value <= 2.0
+    Price is above VWAP and within 2 standard deviations. Constructive
+    for bulls — price is pricier than the rolling average but not at
+    statistical extremes.
+
+  value > -0.5 AND value < 0.5
+    Price is near VWAP — at the volume-weighted fair value anchor.
+    Neutral positioning. Neither bulls nor bears have a strong cost basis
+    advantage at current price.
+
+  value >= -2.0 AND value <= -0.5
+    Price is below VWAP. Bears hold the cost basis advantage. Downside
+    conditions are in effect but not at statistical extremes.
+
+  value < -2.0
+    Price is significantly below VWAP. Extended bearish territory.
+    Mirror of > 2.0. Mean-reversion risk from the downside is elevated
+    when combined with oversold RSI or bullish divergence conditions.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.vwap | REQUIRED_COMPANION
+    vwap_zscore is meaningless without knowing the absolute VWAP level.
+    Reference vwap (price level) alongside the z-score for context.
+
+  indicators.bayesian_overbought | CROSS_VALIDATE FOR EXTENDED STATES
+    IF vwap_zscore > 2.0 AND bayesian_overbought > 0.88
+      → Price is far above VWAP AND the RSI reading is in the top percentile
+         of recent history. Both independent metrics agree price is historically
+         extended upward. Highest compound warning for upside mean-reversion risk.
+
+    IF vwap_zscore < -2.0 AND bayesian_overbought < 0.12
+      → Mirror: price far below VWAP + RSI at recent historical bottom.
+         Highest compound signal for downside mean-reversion risk.
+
+  indicators.support / indicators.resistance | CONTEXT
+    A support level that coincides with VWAP has dual anchoring — it is both
+    a frequently-tested price level AND the volume-weighted cost basis.
+    vwap_zscore near 0 will often coincide with active support/resistance zones.
+
+  indicators.hfi | CONTEXT
+    HFI captures funding/OI/CVD-based sentiment.
+    IF vwap_zscore > 2.0 AND hfi > 30
+      → Price far extended above VWAP WITH positive funding/OI positioning.
+         Both price and derivatives market are bullish and extended.
+         Elevated risk if HFI reverses (funding flips negative).
+
+  indicators.volatility_clustering | ADJUSTS INTERPRETATION
+    This indicator modulates vwap_zscore thresholds internally.
+    In high volatility-clustering periods, the "extreme" bands widen.
+    Be aware that the same z-score number means different things under
+    different volatility clustering conditions.
+
+  indicators.hurst_exponent | COMPANION FOR MEAN REVERSION
+    IF hurst < 0.4 AND |vwap_zscore| > 2.0
+      → Price extended beyond 2σ in a historically mean-reverting asset.
+         Two independent factors both favor a return toward VWAP.
+
+  indicators.poc_distance | CONTEXT
+    IF vwap_zscore > 2.0 AND poc_distance > 3.0
+      → Price is both above VWAP (cost basis) and far above the Point of
+         Control (highest-volume price). Double extension signal.
+
+  indicators.regime | CONTEXT
+    During CASCADE/PARABOLIC: vwap_zscore can sustain high values for extended
+    periods. Do not use FAR_ABOVE as a mean-reversion trigger in these regimes.
+    During CHOP/CONSOL: FAR ABOVE/BELOW is a stronger mean-reversion signal
+    as there is no trend to sustain the extension.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Read vwap_zscore and range bucket.
+  2  If |value| > 2.0: note regime — in trending regimes (CASCADE/BREAKOUT),
+     large z-scores may persist rather than mean-revert.
+  3  If |value| > 2.0: cross-validate with bayesian_overbought.
+  4  Mean-reversion context: add hurst_exponent and support/resistance.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF vwap is not available (insufficient candle history): discard.
+
+  IF stdDev ≈ 0 (near constant-price period)
+    → z-score becomes unstable. Check if asset is temporarily illiquid.
+       Use activity_ratio to detect.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF vwap_zscore > 2.0 is automatically treated as a short entry signal
+    → INCORRECT USE. Extended z-scores can persist in strong trends.
+       In CASCADE regimes, z-score > 3.0 is a continuation signal, not
+       a reversal signal. Gate by regime first.
+
+  IF threshold values are compared without adjusting for volatility_clustering
+    → INCOMPLETE. vwap_zscore thresholds are dynamically adjusted by
+       volatility_clustering multiplier. The same absolute z-score number
+       means different things in high vs low clustering environments.

package/docs/ai-agent-indicators/weighted_rsi.txt

@@ -0,0 +1,148 @@
+================================================================================
+INDICATOR: WEIGHTED_RSI — MULTI-TIMEFRAME WEIGHTED RSI (OBOS)
+================================================================================
+id:                 weighted_rsi
+data_field:         indicators.weighted_rsi
+type:               NUMERIC
+range:              0.0 to 100.0
+precision:          2 decimal places
+update_rate:        per_tick
+latency_profile:    COINCIDENT
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+weighted_rsi is a multi-timeframe RSI that blends RSI readings across all 12
+timeframes into a single number, applying exponential decay weights that
+heavily favor shorter timeframes but retain longer-TF context.
+
+Per-timeframe weights (exponential decay):
+  1m: 1.00  |  3m: 0.80  |  5m: 0.64  |  15m: 0.51  |  30m: 0.41  |  1h: 0.33
+  2h: 0.26  |  4h: 0.21  |  6h: 0.17  |  8h: 0.13  |  12h: 0.11  |  24h: 0.08
+
+RSI computation per TF:
+  avgGain = average of positive changes over window
+  avgLoss = average of |negative| changes over window
+  rs = (avgGain + 0.001) / (avgLoss + 0.001)   [epsilon prevents division by zero]
+  rsi_tf = 100 - 100 / (1 + rs)
+
+Weighted composite:
+  value = Σ(rsi_tf × weight) / Σ(weight) before EWMA smoothing
+
+EWMA smoothing applied:
+  smoothedValue = alpha × raw + (1 - alpha) × prevSmoothed  (alpha = 0.3)
+
+Dead zone: if total price movement across all TFs < 0.01, returns smoothed 50.
+
+The 1m timeframe has by far the largest weight (1.00 vs 0.08 for 24h), meaning
+shorter-term RSI conditions dominate this indicator. Long-TF RSI context
+contributes but takes many ticks to shift the composite materially.
+
+--------------------------------------------------------------------------------
+RANGE INTERPRETATION
+--------------------------------------------------------------------------------
+  value >= 80
+    Heavily overbought across the short-TF stack. Short-term RSI conditions
+    are at extreme levels. Upward momentum has been very strong in recent
+    bar-by-bar changes. Historically associated with short-TF exhaustion or
+    continuation after high-momentum breakouts.
+
+  value >= 70 AND value < 80
+    Overbought zone. Short-to-medium TF RSIs are elevated. Upside momentum
+    is stretched. Does not indicate a reversal but does indicate momentum
+    sustainability is reduced. Use Bayesian P(Overbought) to assess vs
+    historical percentile.
+
+  value >= 55 AND value < 70
+    Mild upside bias. RSI conditions favor the upside but without extremity.
+    Momentum is present without being stretched. Constructive environment
+    for upside continuation from a momentum standpoint.
+
+  value >= 45 AND value < 55
+    Neutral. Balanced buy/sell pressure in RSI terms. No directional bias
+    from momentum at the cross-TF level. Check other indicators for direction.
+
+  value >= 30 AND value < 45
+    Mild downside bias. Short-TF RSI slightly favors the downside.
+    Some downside momentum present. 
+
+  value >= 20 AND value < 30
+    Oversold zone. Short-to-medium TF RSIs are depressed. Downside momentum
+    is stretched. Does not indicate a reversal but does indicate downside
+    sustainability is reduced.
+
+  value < 20
+    Heavily oversold. Extreme downside RSI across the short-TF stack.
+    Mirror of >= 80 upside interpretation.
+
+--------------------------------------------------------------------------------
+RELATED FIELDS THAT SHARE THIS COMPUTATION
+--------------------------------------------------------------------------------
+  indicators.rsi_divergence
+    Computed within the same OBOS system. Detects divergence between
+    price slope and OBOS (weighted_rsi) slope. See rsi_divergence.txt.
+
+  indicators.bayesian_overbought
+    Uses this same weighted_rsi value to compute an empirical percentile
+    over a 60-observation rolling window. See bayesian_overbought.txt.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.bayesian_overbought | REQUIRED_COMPANION
+    weighted_rsi alone cannot distinguish whether "overbought" at 75 is
+    historically extreme or normal for this asset.
+    Check bayesian_overbought alongside weighted_rsi.
+    IF weighted_rsi >= 70 AND bayesian_overbought >= 0.9
+      → Confirmed overbought: reading is both extreme in absolute terms
+         AND at the high end of the asset's recent history.
+    IF weighted_rsi >= 70 AND bayesian_overbought = 0.6
+      → RSI is elevated but historically common for this asset.
+         Less likely to produce a mean-reversion response.
+
+  indicators.rsi_divergence | CONTEXT
+    Divergence is meaningful only when weighted_rsi approaches extremes.
+    IF weighted_rsi < 40 AND rsi_divergence = BULLISH_DIVERGENCE
+      → Price making lower lows but oversold RSI is improving. Monitors
+         a potential momentum shift from downside.
+
+  indicators.hmi | CROSS_VALIDATE
+    HMI is weighted toward medium TFs (1h carries more than 1m alone).
+    weighted_rsi is weighted toward the shortest TFs.
+    Agreement between high hmi and elevated weighted_rsi is normal.
+    Divergence (high hmi, low weighted_rsi or vice versa) indicates the
+    two timeframe bands are moving differently.
+
+  indicators.regime | GATE
+    IF regime = CHOP: weighted_rsi near 50 is expected. No signal.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Regime/activity gate: if CHOP or activity_ratio < 0.5, discard.
+  2  Read value and range bucket.
+  3  Frame with bayesian_overbought for historical percentile context.
+  4  Check rsi_divergence if value is above 65 or below 35.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF activity_ratio < 0.5
+    → Very low volume makes RSI calculations unreliable. Discard.
+
+  IF value is exactly 50.0 in a moving market
+    → Likely dead zone trigger (total movement < 0.01). Treat as INDETERMINATE.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF weighted_rsi >= 70 is used as a reversal signal
+    → INCORRECT USE. RSI overbought is a caution signal, not a reversal
+       trigger. During strong trending markets, weighted_rsi can hold above
+       70 for many consecutive ticks. Combine with bayesian_overbought and
+       regime to assess whether reversal probability is meaningful.
+
+  IF weighted_rsi smoothing lag is ignored in fast markets
+    → EWMA alpha=0.3 provides meaningful smoothing. Rapid price moves
+       will not immediately push weighted_rsi to extremes. Regime and
+       vwap_zscore may react faster to sudden moves than weighted_rsi.