@pgnio/helios-mcp 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,131 @@
+================================================================================
+INDICATOR: POC — POINT OF CONTROL (VOLUME PROFILE)
+================================================================================
+id:                 poc
+data_field:         indicators.poc
+type:               PRICE LEVEL (same units as current price)
+range:              Positive real number; located within recent price range
+precision:          Asset tick size
+update_rate:        per_tick (updates with each new 1m candle)
+latency_profile:    SLOW (computed from rolling candle history)
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+POC (Point of Control) is the price level with the highest trading volume
+over the observation window.
+
+Computation:
+  1. Determine price range: rangeLow to rangeHigh over all available candles.
+  2. Divide price range into 50 equal-width buckets.
+  3. For each candle: distribute its volume to buckets proportionally by
+     overlap between the candle's [low, high] range and each bucket.
+  4. POC = midpoint of the bucket with the highest accumulated volume.
+
+Also computed from the same volume bucket pass:
+  Value Area: the 70% volume zone centered on/around POC (greedy expansion)
+  → indicators.value_area_high = upper edge of Value Area
+  → indicators.value_area_low  = lower edge of Value Area
+  (See value_area_position.txt for Value Area documentation.)
+
+POC represents the "fairest price" by volume — the level where the market
+has spent the most transactional effort over the observed history. It acts
+as a powerful gravitational magnet attracting price back to it from extremes,
+and also as a pivot level that, once broken with confidence, becomes a barrier.
+
+--------------------------------------------------------------------------------
+INTERPRETATION: POC AS A PRICE LEVEL
+--------------------------------------------------------------------------------
+  price ≈ POC (within 1% or one standard deviation)
+    Price is near the high-volume node. This is the price level where the
+    most historical trading occurred. Strong balance and institutional anchoring.
+    Expect responsive price behavior — continuation breaks from POC require
+    volume conviction; fades often occur from POC during range-bound conditions.
+
+  price > POC
+    Price is trading above the highest-activity zone. Buyers who accumulated
+    near POC are in profit. POC acts as potential support if price returns.
+
+  price < POC
+    Price is below the highest-activity zone. Sellers who distributed near POC
+    are in profit. POC may act as resistance if price returns from below.
+
+  Price far from POC (see poc_distance):
+    The further price is from POC, the more likely POC will exert gravitational
+    pull. However, breaking far from POC with sustained momentum suggests
+    new price discovery and potential creation of a new POC at the new level.
+
+--------------------------------------------------------------------------------
+RELATED FIELDS
+--------------------------------------------------------------------------------
+  indicators.poc_distance
+    The % distance from current price to POC. See poc_distance.txt.
+    Positive = price above POC. Negative = price below POC.
+
+  indicators.value_area_high
+  indicators.value_area_low
+    Upper and lower edges of the Value Area (70% volume zone).
+    See value_area_position.txt.
+
+  indicators.value_area_position
+    Categorical: "ABOVE VA" | "IN VA" | "BELOW VA"
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.poc_distance | REQUIRED_COMPANION
+    poc (price level) must be read with poc_distance (deviation %) to be
+    actionable. poc_distance normalizes the raw price-to-POC gap into
+    percentage terms for cross-asset comparison.
+
+  indicators.vwap | CONTEXT
+    VWAP = time-volume weighted average. POC = highest-volume node.
+    These often coincide in balanced markets. When they diverge:
+    - POC > VWAP: more recent volume at higher prices (even if time-avg is lower)
+    - POC < VWAP: older/higher volume transactions below current VWAP
+
+    IF price between POC and VWAP: price is in a zone of intense historical
+    volume AND near cost basis. Strongest structural support/resistance zone.
+
+  indicators.support / indicators.resistance | AMPLIFIES
+    Support or resistance levels that coincide with POC are the highest-
+    probability levels in the entire indicator set. Two independent methods
+    (volume distribution + price pivot analysis) identifying the same level
+    amplifies the significance substantially.
+
+  indicators.vwap_zscore | CONTEXT
+    IF poc_distance > 3% AND vwap_zscore > 2.0
+      → Price well above both POC and VWAP. Extended from two separate
+         volume-anchored references simultaneously. Magnitude of extension
+         is more significant when both agree.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Read poc (price level); note price vs poc direction.
+  2  Read poc_distance for normalized deviation.
+  3  Read value_area_position for coarser zone context.
+  4  Compare poc to active support/resistance levels.
+  5  Compare poc to vwap level.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF no candle history available: POC cannot be computed.
+
+  IF recent extreme price move has expanded range significantly
+    → The 50-bucket grid will have re-bucketed. POC may shift suddenly.
+       Monitor poc_distance for discontinuities that indicate range recompute.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF poc is treated as support on its own without volume confirmation
+    → INCOMPLETE. POC indicates high volume at a level; it does not
+       guarantee the level will hold. Check the Bayesian strength
+       from the support/resistance indicator for hold probability.
+
+  IF POC is used to predict short-term price targets
+    → POC is a gravitational anchor, not a directional predictor.
+       Price can trade far from POC for extended periods during breakout
+       regimes. POC-based mean-reversion logic should be gated by regime.

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

@@ -0,0 +1,129 @@
+================================================================================
+INDICATOR: POC_DISTANCE — DISTANCE FROM POINT OF CONTROL
+================================================================================
+id:                 poc_distance
+data_field:         indicators.poc_distance
+type:               NUMERIC  (percentage)
+range:              Unbounded; positive = above POC, negative = below
+precision:          2 decimal places
+update_rate:        per_tick
+latency_profile:    SLOW (inherits POC computation)
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+poc_distance measures the percentage distance of the current price from the
+Point of Control (the highest-volume price level over the observation window).
+
+Formula:
+  poc_distance = ((currentPrice - poc) / poc) × 100
+
+Positive: price is trading ABOVE the POC.
+Negative: price is trading BELOW the POC.
+Zero: price is exactly at the POC.
+
+This normalizes the raw price-to-POC gap into percentage terms, enabling
+comparison across assets with different price levels.
+
+--------------------------------------------------------------------------------
+RANGE INTERPRETATION
+--------------------------------------------------------------------------------
+  value > 5.0
+    Price is more than 5% above the highest-activity historical level.
+    Far above the volume equilibrium zone. Upside price discovery in progress.
+    The asset is trading in a thin volume area above its most-traded level.
+
+  value > 2.0 AND value <= 5.0
+    Price is moderately extended above POC. Above the main value zone.
+    Volume support exists below at POC level but price has moved away.
+
+  value > 0.5 AND value <= 2.0
+    Price is near POC on the upside. Minimal extension. Trading within
+    normal distance from the high-volume anchor.
+
+  value >= -0.5 AND value <= 0.5
+    Price is essentially AT the POC. Highest historical volume zone.
+    Strong two-way order flow expected. Price is in the "fairest value" zone.
+
+  value >= -2.0 AND value < -0.5
+    Price is near POC on the downside. Minimal extension below.
+
+  value >= -5.0 AND value < -2.0
+    Price is moderately extended below POC.
+
+  value < -5.0
+    Price is more than 5% below the highest-activity level. Far below volume
+    equilibrium. Downside price discovery in progress.
+
+--------------------------------------------------------------------------------
+POC MEAN-REVERSION THESIS
+--------------------------------------------------------------------------------
+# The key use of poc_distance is assessing mean-reversion probability toward POC.
+# This thesis only applies when regime does NOT support continuation.
+
+  Conditions that support POC mean-reversion:
+    |poc_distance| > 3.0          (price far from equilibrium)
+    AND regime IN [CHOP, CONSOL, RANGING, EXHAUST_UP, EXHAUST_DN]
+    AND trend_interpretation IN [WEAK, RANGING_CHOPPY]
+    AND |vwap_zscore| > 1.5       (also extended from VWAP)
+
+  Conditions that reduce POC mean-reversion probability:
+    regime IN [CASCADE, BREAKOUT, PARABOLIC]   (trend is sustaining extension)
+    AND activity_ratio >= 1.5                  (high-volume breakout)
+    → Extended poc_distance in these conditions is a breakout signal,
+       not a mean-reversion signal. POC is being left behind.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.poc | REQUIRED_COMPANION
+    poc_distance is meaningless without knowing the absolute poc price level.
+    Always read poc (level) and poc_distance (deviation) together.
+
+  indicators.value_area_position | CONTEXT
+    IF value_area_position = "IN VA" AND |poc_distance| < 1.5
+      → Price is both within the 70% value area AND near the POC specifically.
+         Maximum historical volume anchor engagement.
+
+    IF value_area_position = "ABOVE VA" AND poc_distance > 3.0
+      → Price is outside the value area AND far from POC. Double extension.
+
+  indicators.vwap_zscore | AMPLIFIES
+    IF poc_distance > 3.0 AND vwap_zscore > 2.0
+      → Price extended above both POC and VWAP simultaneously. Strongest
+         compound mean-reversion precondition.
+
+  indicators.regime | GATE
+    Gate ALL POC mean-reversion logic on regime. In trending (CASCADE/BREAKOUT)
+    regimes, large poc_distance is EXPECTED and self-reinforcing.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Read poc_distance (percentage deviation).
+  2  Sign: positive = above POC, negative = below.
+  3  Regime gate: in trending regimes (CASCADE/BREAKOUT), large poc_distance
+     is continuation context, not mean-reversion signal.
+  4  Cross-reference with value_area_position and vwap_zscore.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF poc is unavailable: poc_distance is unavailable. Discard.
+
+  IF |poc_distance| changes by > 2% in a single tick
+    → May indicate POC level recomputed due to price range expansion.
+       Treat as potentially stale until next stable reading.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF poc_distance > 3.0 is used as a short signal in a trending market
+    → INCORRECT. In BREAKOUT/CASCADE/PARABOLIC: large poc_distance is
+       confirmation of the move, not reversal signal. The POC may follow
+       price higher as new volume accumulates at higher levels.
+
+  IF poc_distance is compared without considering sign direction
+    → poc_distance can be +3 or -3. For assessing "how far from POC"
+       without directional context, use |poc_distance|. For directional
+       assessment (above vs below), use the signed value.

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

@@ -0,0 +1,225 @@
+================================================================================
+INDICATOR: REGIME — MARKET REGIME CLASSIFIER
+================================================================================
+id:                 regime
+data_field:         indicators.regime
+type:               CATEGORICAL
+values:             CASCADE_UP, CASCADE_DOWN, PARABOLIC, CRASH, BREAKOUT,
+                    BREAKDOWN, REVERSAL, ROLLOVER, TREND_UP, TREND_DN,
+                    GRIND_UP, BLEED, SPIKE_UP, SPIKE_DN, EXHAUST_UP,
+                    EXHAUST_DN, CHOP, CONSOL, RANGING
+update_rate:        per_tick (with 15-second dwell anti-flap protection)
+latency_profile:    COINCIDENT
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+Regime classifies the current overall market state from 12 timeframe change
+values. It is computed using a multi-condition scoring system: every eligible
+regime receives a score, and the regime with the highest score wins. A 15-second
+dwell timer prevents rapid flapping between regimes on ambiguous ticks.
+
+Inputs used:
+  - Raw % change across all 12 timeframes (1m through 24h)
+  - Timeframe clusters: micro [1m,3m,5m], short [15m,30m,1h],
+    medium [2h,4h,6h], macro [8h,12h,24h]
+  - Derived: microAvg, shortAvg, mediumAvg, macroAvg
+  - Derived: totalStrength (avg absolute change across all 12 TFs)
+  - Derived: positiveTFs, negativeTFs (counts of TFs in each direction)
+  - Derived: avgAccel (weighted acceleration across clusters)
+  - Derived: activity_ratio, volc_confidence (for REVERSAL/ROLLOVER gate)
+
+Key computed thresholds:
+  veryStrong          = totalStrength > 3
+  strong              = totalStrength > 2
+  moderate            = totalStrength > 1
+  fullAlignment       = all 12 TFs agree on direction
+  strongAlignment     = 10+ TFs agree on direction
+  moderateAlignment   = 8+ TFs agree on direction
+  strongAcceleration  = avgAccel > 0.5
+  strongDeceleration  = avgAccel < -0.5
+  cascade (upward)    = microAvg > shortAvg > mediumAvg > 0
+                        (momentum STARTING from micro and propagating outward)
+
+--------------------------------------------------------------------------------
+REGIME DEFINITIONS — EXACT CONDITIONS
+--------------------------------------------------------------------------------
+# Listed in descending score priority order.
+# Each is fully self-contained.
+
+CASCADE_UP  (base score ~95+)
+  All 12 TFs aligned upward (fullAlignment or strongAlignment).
+  Momentum is largest at micro (1m-5m) and decreasing toward macro —
+  the move is starting from the shortest timeframes and propagating outward.
+  Total strength is veryStrong. Acceleration is strongly positive.
+  This is the highest-conviction upside regime. The move is self-sustaining
+  and expanding across the timeframe stack.
+
+CASCADE_DOWN  (base score ~95+)
+  Mirror of CASCADE_UP with all clusters negative.
+  microAvg is most negative, becoming less negative toward macroAvg.
+  Momentum is starting from shortest TFs and cascading outward in the
+  downside direction.
+
+PARABOLIC  (base score ~90+)
+  All 12 TFs aligned upward (fullAlignment required).
+  Every cluster is contributing with high magnitude.
+  Strong acceleration present.
+  Does NOT require cascade structure — differs from CASCADE_UP in that
+  ALL timeframes are extreme simultaneously, not sequentially propagating.
+
+CRASH  (base score ~90+)
+  Mirror of PARABOLIC. All TFs extreme negative simultaneously.
+
+BREAKOUT  (base score ~85+)
+  10+ TFs aligned upward (strongAlignment). TotalStrength is veryStrong.
+  Strong acceleration present.
+  The breakout is confirmed across short and medium TFs but may not have
+  fully reached macro TFs yet. An additional +5 score if aligned TF count >= 10.
+
+BREAKDOWN  (base score ~85+)
+  Mirror of BREAKOUT. 10+ TFs aligned downward with strong acceleration.
+
+REVERSAL  (base score ~72+, PARTICIPATION GATED)
+  Gate requirements — ALL must be true:
+    activity_ratio >= 1.0   (volume must be above normal)
+    volc_confidence >= 1.05 (volume clustering must be active)
+  Core conditions:
+    macroAvg <= -1.25       (macro TFs still significantly negative)
+    microAvg >= 0.9         (short TFs strongly positive and reversing)
+    2+ micro TFs positive
+    microAvg > shortAvg     (micro recovery leading short TFs)
+  This regime identifies a genuine directional shift from down to up,
+  distinguished from a SPIKE_UP by requiring volume participation and
+  structural macro alignment against which micro is recovering.
+
+ROLLOVER  (base score ~72+, PARTICIPATION GATED)
+  Mirror of REVERSAL. macroAvg positive, micro turning strongly negative.
+  Same gate requirements (activity + volc).
+
+TREND_UP  (base score ~65+)
+  8+ TFs aligned upward (moderateAlignment). TotalStrength is strong.
+  Less extreme than BREAKOUT — not all TFs agree and/or acceleration
+  is not exceptional. Established upward trend with broad but not full
+  consensus.
+
+TREND_DN  (base score ~65+)
+  Mirror of TREND_UP. 8+ TFs negative, strong aggregate.
+
+SPIKE_UP  (base score ~60+)
+  Micro TFs (1m-5m) are strongly positive (|microAvg| > 3).
+  Macro TFs are near zero (|macroAvg| < 1).
+  Short-TF move with NO macro confirmation. The move is isolated to
+  shortest timeframes only. Continuation probability is low unless
+  BREAKOUT or TREND regimes follow.
+
+SPIKE_DN  (base score ~60+)
+  Mirror of SPIKE_UP. Micro strongly negative, macro flat.
+
+GRIND_UP  (base score ~55+)
+  Moderate aggregate (totalStrength > 1) but NOT moderateAlignment.
+  No strong acceleration or deceleration.
+  Low-conviction upward drift. TFs partially agree on direction but
+  without the breadth or magnitude of TREND_UP.
+
+BLEED  (base score ~55+)
+  Mirror of GRIND_UP. Moderate downside drift without strong alignment.
+
+EXHAUST_UP  (base score ~45-50+)
+  Either: strong aggregate (totalStrength > 2) WITH strong deceleration
+  (avgAccel < -0.5).
+  Or: |macroAvg| > 2 AND momentumDecay < 0.3 (micro has given up < 30%
+  of macro momentum — macro is strong but micro is nearly exhausted).
+  This regime indicates macro TFs are still bullish but micro TFs are
+  weakening. The trend infrastructure is intact but the short-TF engine
+  has stalled. Probability of continued upside is reduced.
+
+EXHAUST_DN  (base score ~45-50+)
+  Mirror of EXHAUST_UP. Macro still bearish, micro recovering or stalling.
+
+CHOP  (base score 30)
+  No moderateAlignment, no cascade, no strongAlignment.
+  Timeframes are actively disagreeing. No dominant direction. This is
+  the worst regime for directional inference — do not use HMI, hmi_velocity,
+  or any momentum-derived indicators when regime = CHOP.
+
+CONSOL  (base score 25)
+  All timeframes have near-zero changes.
+  totalStrength < 0.5 AND |avgAccel| < 0.2.
+  Price is consolidating / compressing. Momentum-based indicators carry
+  no information in this state. Volatility squeeze indicators are most
+  relevant here.
+
+RANGING  (base score 20+, fallback)
+  Always computed as a fallback option. Wins only if no other regime scores
+  higher. Low-activity, low-conviction state with minimal participation.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.hmi | CROSS_VALIDATE
+    Regime and HMI are computed from the same underlying TF data but via
+    different methods. When they agree, both signals are higher confidence.
+    When they conflict, reduce weight on both.
+    See hmi.txt INDICATOR RELATIONSHIPS section for full conflict rules.
+
+  indicators.hmi_velocity | CONTEXT
+    EXHAUST_UP / EXHAUST_DN regimes should be confirmed by negative/positive
+    hmi_velocity respectively. If regime shows exhaustion but hmi_velocity
+    disagrees, treat both as lower confidence.
+
+  indicators.activity_ratio | PREREQUISITE FOR REVERSAL/ROLLOVER
+    REVERSAL and ROLLOVER regimes require activity_ratio >= 1.0.
+    If activity_ratio is below this threshold, REVERSAL/ROLLOVER cannot
+    be active by construction. If data shows otherwise, treat as stale data.
+
+  indicators.volatility_squeeze.value | CONTEXT FOR CONSOL
+    CONSOL regime co-occurring with low volatility_squeeze.value (< 0.5)
+    indicates maximum compression. Treat as highest-priority squeeze setup.
+
+  indicators.tf_alignment | AMPLIFIES
+    CASCADE and BREAKOUT regimes imply high tf_alignment by construction.
+    If data shows CASCADE_UP with tf_alignment < 70, check for data freshness.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Read regime value.
+  2  IF CHOP, CONSOL, or RANGING: momentum-derived indicators are invalid in this state.
+     EXHAUST_UP/EXHAUST_DN: flag as peak warning; confirm with hmi_velocity.
+  3  Cross-validate with HMI direction; apply conflict rules from INDICATOR RELATIONSHIPS.
+  4  Apply regime to amplify or discount other indicator readings.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  Regime itself is not invalidated by other indicators — it is an INPUT
+  that invalidates others. See each indicator file for regime-based gates.
+
+  # The one internal limitation:
+  IF tick data is stale (updatedAt timestamp > 30 seconds old)
+    → The 15-second dwell timer means the displayed regime may be 1-2
+      transitions behind current market state. Treat as lower confidence.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF EXHAUST_UP is being used as a short entry signal
+    → INCOMPLETE USE. EXHAUST_UP means macro is still bullish and micro
+       is weakening. It is an early warning, not a confirmed reversal.
+       Wait for ROLLOVER or BREAKDOWN regime to confirm the turn.
+
+  IF SPIKE_UP is being treated equivalently to BREAKOUT
+    → INCORRECT USE. SPIKE_UP explicitly means macro TFs are NOT
+       confirming the move. It is an unconfirmed short-TF impulse.
+       Macro TFs (8h-24h) must be monitored for follow-through.
+
+  IF REVERSAL regime is used without checking activity_ratio
+    → DATA INTEGRITY CHECK REQUIRED. REVERSAL requires activity_ratio >= 1.0
+       by construction. If you see REVERSAL with low activity, the data feed
+       may be supplying stale activity values.
+
+  IF CHOP regime is active AND any momentum indicator is being used for direction
+    → INVALIDATION NOT APPLIED. Under CHOP: HMI, hmi_velocity, MACD,
+       Weighted RSI, TF Alignment — all should be discarded. Their values
+       reflect TF noise, not directional state.

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

@@ -0,0 +1,145 @@
+================================================================================
+INDICATOR: RSI_DIVERGENCE — OBOS RSI DIVERGENCE
+================================================================================
+id:                 rsi_divergence
+data_field:         indicators.rsi_divergence
+type:               CATEGORICAL
+values:             BULLISH_DIVERGENCE | BEARISH_DIVERGENCE | NONE
+update_rate:        per_tick
+latency_profile:    LAGGING (computed over 20-bar slope window)
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+IMPORTANT: rsi_divergence is NOT a standalone computed indicator. It is
+produced by the detectDivergence() function embedded within the weighted RSI
+(OBOS) system. It is emitted alongside indicators.weighted_rsi.
+
+Computation:
+  lookback window: 20 bars
+
+  Price slope proxy (multi-TF weighted):
+    priceSlope = change1m × 0.5 + change3m × 0.3 + change5m × 0.2
+    (normalized 0-1 range before slope comparison)
+
+  OBOS slope:
+    slope of indicators.weighted_rsi values over the same 20-bar window
+
+  Slope threshold: 0.15 (normalized)
+
+  BULLISH_DIVERGENCE:
+    priceSlope < -0.15   (price trending downward)
+    AND
+    obsSlope > 0.15      (weighted_rsi trending upward)
+    → Price is making lower lows but RSI is making higher lows.
+      Downside momentum is weakening relative to price.
+
+  BEARISH_DIVERGENCE:
+    priceSlope > 0.15    (price trending upward)
+    AND
+    obsSlope < -0.15     (weighted_rsi trending downward)
+    → Price is making higher highs but RSI is making lower highs.
+      Upside momentum is weakening relative to price.
+
+  NONE: neither condition met.
+
+--------------------------------------------------------------------------------
+STATE DEFINITIONS
+--------------------------------------------------------------------------------
+  BULLISH_DIVERGENCE
+    Over the last 20 bars, price has moved downward while weighted_rsi has
+    moved upward. This means the downside price movement is not accompanied
+    by strong selling momentum — RSI is improving despite lower prices.
+    Associated with potential momentum exhaustion in a downtrend or with
+    price nearing a local bottom that RSI has already turned from.
+
+  BEARISH_DIVERGENCE
+    Over the last 20 bars, price has moved upward while weighted_rsi has moved
+    downward. Upside price movement is not accompanied by building momentum.
+    RSI is deteriorating despite higher prices. Associated with potential
+    momentum exhaustion in an uptrend.
+
+  NONE
+    No meaningful divergence slope condition. Either slopes agree, or one
+    or both are below the 0.15 threshold (insufficient trend in either).
+
+--------------------------------------------------------------------------------
+IMPORTANT CONSTRAINT
+--------------------------------------------------------------------------------
+# Divergence is only informative when weighted_rsi is near extremes.
+# Divergence detected when weighted_rsi is between 40 and 60 is meaningless.
+# Threshold filter:
+
+  IF rsi_divergence = BULLISH_DIVERGENCE AND weighted_rsi > 40
+    → Divergence detected in neutral RSI territory. Not meaningful.
+       RSI was not oversold when the divergence formed.
+
+  IF rsi_divergence = BEARISH_DIVERGENCE AND weighted_rsi < 60
+    → Divergence detected in neutral RSI territory. Not meaningful.
+
+  VALID BULLISH DIVERGENCE:    rsi_divergence = BULLISH AND weighted_rsi <= 35
+  VALID BEARISH DIVERGENCE:    rsi_divergence = BEARISH AND weighted_rsi >= 65
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.weighted_rsi | REQUIRED_COMPANION
+    rsi_divergence has no meaning without the current weighted_rsi level.
+    Apply the extreme-zone filter above before treating any divergence as valid.
+
+  indicators.bayesian_overbought | AMPLIFIES
+    IF rsi_divergence = BEARISH AND bayesian_overbought > 0.85
+      → RSI diverging bearish AND current RSI is historically extreme.
+         Both conditions strengthen the momentum-fade reading.
+    IF rsi_divergence = BULLISH AND bayesian_overbought < 0.15
+      → RSI diverging bullish AND current RSI is historically bottomed.
+         Both conditions strengthen the momentum-recovery reading.
+
+  indicators.macd_divergence | CROSS_VALIDATE
+    macd_divergence is computed independently from MACD histogram peaks.
+    IF rsi_divergence and macd_divergence agree on the same direction
+      → Higher confidence divergence signal, two independent methods
+         both detecting momentum-price separation.
+
+  indicators.hmi_velocity | CONTEXT
+    IF rsi_divergence = BEARISH AND hmi_velocity < -2.0
+      → Momentum fade confirmed by both RSI path and raw HMI deceleration.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Read weighted_rsi value first.
+  2  Apply extreme-zone filter: BULLISH valid only if weighted_rsi <= 35;
+     BEARISH valid only if weighted_rsi >= 65. Discard otherwise.
+  3  Read rsi_divergence state.
+  4  Cross-validate with bayesian_overbought and macd_divergence.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF weighted_rsi is not at an extreme (not <= 35 for BULLISH, not >= 65
+  for BEARISH): divergence is NOT valid. Explicitly discard.
+
+  IF activity_ratio < 0.5: underlying RSI slopes are noise. Discard.
+
+  IF fewer than 20 bars of OBOS history are available
+    → Slope computation requires 20 bars. Output NONE is expected behavior
+       on startup. Do not treat as a signal.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF rsi_divergence is treated as a standalone reversal trigger
+    → INCORRECT USE. Divergence indicates weakening momentum, not confirmed
+       reversal. Price can continue in the divergence direction for many ticks
+       after divergence is detected. Additional confirmation required.
+
+  IF rsi_divergence = BULLISH_DIVERGENCE is used regardless of RSI level
+    → INCORRECT. Bullish divergence detected when RSI is at 55 means
+       nothing — RSI was never oversold. Only divergences forming at
+       extremes are statistically meaningful.
+
+  IF rsi_divergence is expected to reset on each tick
+    → INCORRECT EXPECTATION. Divergence is computed from 20-bar slope.
+       It persists across ticks until price or RSI slopes change
+       significantly. It is a continuous condition assessment, not a one-time event.