@pgnio/helios-mcp 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,305 @@
+================================================================================
+INDICATOR: HMI — HELIOS MOMENTUM INDEX
+================================================================================
+id:                 hmi
+data_field:         indicators.hmi
+type:               NUMERIC
+range:              -100.0 to 100.0
+precision:          1 decimal place
+update_rate:        per_tick (every aggregate trade event)
+latency_profile:    COINCIDENT
+                    # Reflects current cross-timeframe state.
+                    # Does not predict future direction.
+                    # Pair with data_field: indicators.hmi_velocity for direction confirmation.
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+HMI is a weighted composite of momentum z-scores across 12 timeframes (1m–24h).
+
+Each timeframe's raw % change is normalized by its own volatility to produce a
+z-score, then Kalman-filtered for stability, then weighted and summed. The output
+encodes both the DIRECTION and the BREADTH of agreement across the timeframe stack.
+
+The weighting structure is non-uniform and heavily biased toward medium timeframes:
+
+  TIMEFRAME   BASE WEIGHT
+  ---------   -----------
+  1m          0.05
+  3m          0.06
+  5m          0.08
+  15m         0.12
+  30m         0.14
+  1h          0.16   ← single heaviest timeframe
+  2h          0.13
+  4h          0.11
+  6h          0.06
+  8h          0.04
+  12h         0.03
+  24h         0.02
+
+  Combined weight of 1m + 3m + 5m              = 0.19
+  Weight of 1h alone                            = 0.16
+  Combined weight of 1h + 2h + 4h              = 0.40
+
+  # The entire short-TF cluster (1m–5m) is outweighed by 1h alone.
+  # For HMI to reach any extreme, the 1h/2h/4h cluster must agree on direction.
+
+Weights are further modulated per tick by:
+  - Bayesian confidence: low-confidence TF data reduces effective weight
+  - Alignment boost/penalty: TFs agreeing with neighbors get +15%; disagreeing get −15%
+  - Reversion dampener: extreme isolated z-scores are cut 50–80% when coherence is low
+  - Volume exhaustion multiplier: fading volume cuts contribution by up to 20%
+  - HFI cross-feed: derivatives flow alignment adds or subtracts up to 10%
+
+HMI does NOT measure price extension, overbought/oversold state, or reversal probability.
+It measures the degree of directional consensus across the weighted timeframe stack.
+
+--------------------------------------------------------------------------------
+RANGE INTERPRETATION
+--------------------------------------------------------------------------------
+# All ranges are self-contained. No cross-references required.
+# For each range: what the stack state is, and what it means structurally.
+
+  hmi >= 75
+    The 1h/2h/4h cluster AND most shorter timeframes are aligned upward with
+    high magnitude. For this value to be reachable, medium-term TFs (combined
+    weight 0.40) must be strongly positive — short-TF contributions alone cannot
+    produce this reading. Every processing layer (alignment boost, reversion
+    dampener, exhaustion multiplier) is permitting full contribution rather than
+    attenuating. This is a fully established, self-reinforcing momentum state.
+    Historically co-occurs with CASCADE_UP or PARABOLIC regime.
+
+  hmi >= 60 AND hmi < 75
+    Strong directional consensus. The 1h/2h band is clearly positive and 30m is
+    contributing. Short TFs are aligned or neutral. The trend has propagated
+    through the full stack. This level is not reachable from short-TF activity
+    alone — medium/long TF agreement is mathematically required.
+
+  hmi >= 30 AND hmi < 60
+    Moderate consensus. Short and medium TFs agree but long TFs are contributing
+    weakly or are still catching up. This can mean:
+      - A developing trend that hasn't yet propagated to longer TFs
+      - A previous trend where longer TFs are decaying but still positive
+    These two states look identical in the HMI value. hmi_velocity distinguishes
+    them. IF hmi_velocity is unavailable: treat this range as indeterminate.
+
+  hmi >= 15 AND hmi < 30
+    Weak consensus. Primarily driven by short-to-medium TFs. The 1h/4h cluster
+    is near zero or mildly positive. Cannot distinguish early-stage accumulation
+    from momentum tail-off without hmi_velocity. Low structural weight — minor
+    changes in medium TFs will swing this reading significantly.
+
+  hmi > -15 AND hmi < 15
+    No meaningful directional consensus. Timeframes are mixed, opposing, or all
+    near zero. The weighted sum cancels out. This range carries no directional
+    information regardless of what any single timeframe shows. Do not infer
+    direction from HMI at this value.
+
+  hmi > -30 AND hmi <= -15
+    Weak downside consensus. Mirror construct of 15–29 upside range.
+    Same structural interpretation applies: short-to-medium TF driven, ambiguous
+    without hmi_velocity, sensitive to medium TF changes.
+
+  hmi > -60 AND hmi <= -30
+    Moderate downside consensus. Short and medium TFs agree on downside direction.
+    Long TFs are neutral or weakly negative. Mirror construct of 30–59 upside.
+    hmi_velocity required to distinguish developing vs decaying.
+
+  hmi > -75 AND hmi <= -60
+    Strong downside consensus. Mirror construct of 60–74 upside.
+    1h/2h band is clearly negative. Medium/long TF agreement is mathematically
+    present. Trend propagated through the stack.
+
+  hmi <= -75
+    Full-stack downside alignment. Mirror construct of >= 75 upside.
+    1h/2h/4h cluster strongly negative. Historically co-occurs with CASCADE_DOWN
+    or CRASH regime.
+
+--------------------------------------------------------------------------------
+TRAJECTORY EVALUATION
+--------------------------------------------------------------------------------
+# Evaluate using live values of both hmi AND hmi_velocity.
+# hmi_velocity = Kalman-estimated rate of change of hmi, EMA-smoothed.
+# These conditionals must be evaluated before acting on any hmi reading.
+
+  IF hmi >= 30 AND hmi_velocity >= 3.0
+    → Stack is broadening. Alignment expanding to additional timeframes.
+      Reading is likely to strengthen further. Medium TFs are joining short TFs
+      in positive territory.
+
+  IF hmi >= 30 AND hmi_velocity >= 0 AND hmi_velocity < 3.0
+    → Stack holding direction. Pace of gain is slowing. Existing alignment is
+      stable but not expanding. Trend continuation at current pace.
+
+  IF hmi >= 30 AND hmi_velocity < 0
+    → Stack has peaked or is peaking. Short TFs are beginning to diverge from
+      medium TFs. The hmi value reflects where the stack was, not its current
+      trajectory. Treat magnitude as potentially overstated.
+
+  IF hmi >= 60 AND hmi_velocity <= -3.0
+    → Active structural divergence. Long-TF infrastructure is still positive
+      (which is why hmi is still high) but short and medium TFs are reversing.
+      The high hmi value is a lagging artifact. Do not interpret as continuation.
+
+  IF hmi >= 15 AND hmi < 30 AND hmi_velocity >= 2.0
+    → Weak but building. Short-TF alignment is strengthening. Medium TFs may
+      follow. Possible early-stage trend formation.
+
+  IF hmi >= 15 AND hmi < 30 AND hmi_velocity <= 0
+    → Weak and fading. Signal has no actionable content. Discard for this cycle.
+
+  IF hmi > -15 AND hmi < 15 AND ANY direction
+    → Trajectory evaluation is not applicable. Stack is not in consensus.
+      hmi_velocity at near-zero hmi has no directional meaning.
+
+  # Mirror these conditionals for negative hmi values with sign-inverted thresholds.
+  IF hmi <= -30 AND hmi_velocity <= -3.0
+    → Downside stack broadening. Alignment expanding to additional timeframes.
+
+  IF hmi <= -60 AND hmi_velocity >= 3.0
+    → Active structural divergence to upside. Long-TF downside is lagging.
+      hmi value is overstating current downside state.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+# Format: field | relationship_type | operational rule
+
+  indicators.hmi_velocity | REQUIRED_COMPANION
+    At hmi IN -30..30: hmi_velocity is more informative than hmi itself.
+    IF hmi IN -30..30 AND hmi_velocity is not evaluated: mark hmi state as INDETERMINATE.
+    Do not act on hmi in this range without hmi_velocity.
+    At hmi outside -30..30: hmi_velocity determines whether value is current or lagging.
+
+  indicators.regime | CROSS_VALIDATE
+    HMI and regime are computed independently. When they conflict, confidence
+    in both is reduced. Evaluate conflict before using either.
+
+    IF hmi >= 40 AND regime IN [CASCADE_UP, BREAKOUT, TREND_UP]
+      → Full agreement between momentum magnitude and regime classification.
+         Both signals carry higher weight than either alone.
+
+    IF hmi >= 40 AND regime = CHOP
+      → Direct conflict. Regime has detected timeframe disagreement as dominant.
+         HMI reading is likely artifact of isolated TF movement despite weighted sum.
+         Discount hmi. Regime classification takes precedence.
+
+    IF hmi >= 40 AND regime IN [CHOP, CONSOL, RANGING]
+      → Conflict. Do not use hmi for directional inference until they reconcile.
+
+    IF hmi < 20 AND regime = BREAKOUT
+      → Regime is leading hmi. Momentum is building in structure before it has
+         propagated to the full timeframe stack. hmi may strengthen — monitor
+         hmi_velocity for confirmation.
+
+    IF hmi >= 60 AND regime = EXHAUST_UP
+      → Regime is detecting micro-TF divergence while macro TFs remain aligned.
+         hmi will remain high but is approaching structural peak.
+
+  indicators.tf_alignment | AMPLIFIES
+    hmi measures magnitude of the weighted sum. tf_alignment measures what
+    percentage of timeframes agree on direction. These are different dimensions.
+
+    IF hmi >= 60 AND tf_alignment >= 80
+      → Maximum signal quality. High magnitude AND high breadth. Full stack
+         agreement on both count and weighted contribution.
+
+    IF hmi >= 60 AND tf_alignment < 50
+      → Magnitude is concentrated in a subset of timeframes (likely 1h/2h with
+         high weight). Many TFs are neutral or opposing. Alignment is not broad.
+         Reduce confidence in directional inference.
+
+    IF hmi < 40 AND tf_alignment >= 80
+      → High breadth but low magnitude. Many TFs agree on direction but none
+         have strong momentum. Low-energy directional state.
+
+  indicators.hfi | CROSS_VALIDATE
+    HMI reflects price-derived momentum across timeframes. HFI reflects derivatives
+    market positioning (funding rate, open interest, CVD). These measure different
+    constructs. Agreement between them increases inference confidence.
+
+    IF hmi >= 40 AND hfi >= 20
+      → Price momentum confirmed by derivatives flow. Institutional positioning
+         is aligned with the timeframe stack direction.
+
+    IF hmi >= 40 AND hfi <= -10
+      → Divergence. Derivatives market is positioned against price momentum.
+         One signal will prove correct. Reduce confidence in both. Do not
+         treat hmi as standalone sufficient.
+
+    IF hmi <= -40 AND hfi >= 10
+      → Divergence in downside move. Derivatives players are buying while price
+         momentum is negative. Potential precursor to reversal — monitor hmi_velocity.
+
+  indicators.activity_ratio | PREREQUISITE_GATE
+    HMI is computed from trade flow z-scores. Insufficient volume degrades
+    signal quality. Gate is monotonic: reducing below 0.8 reduces confidence
+    continuously toward full invalidation at 0.5.
+
+    IF activity_ratio >= 0.8: hmi is volume-supported, full weight.
+    IF activity_ratio >= 0.5 AND activity_ratio < 0.8: reduce confidence in hmi.
+    IF activity_ratio < 0.5: see INVALIDATION.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  INVALIDATION CONDITIONS (activity_ratio, regime) — discard if met.
+  2  RANGE INTERPRETATION — determine current stack state.
+  3  TRAJECTORY — combine with hmi_velocity; mark INDETERMINATE if hmi IN -30..30 and velocity unavailable.
+  4  CROSS-VALIDATE with regime (conflict rules in INDICATOR RELATIONSHIPS).
+  5  BREADTH — assess via tf_alignment for magnitude-breadth divergence.
+  6  DERIVATIVES — cross-validate with hfi if available.
+  7  VOLUME GATE — reduce confidence if activity_ratio < 0.8.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+# IF any condition below is true: discard hmi entirely.
+# Do not use hmi for any inference when invalidated.
+
+  IF activity_ratio < 0.5
+    → Insufficient trade volume. Z-scores are computed from noise-level flow.
+      The weighted sum has no statistical reliability regardless of magnitude.
+
+  IF regime = CHOP
+    → Regime classifier has determined active timeframe disagreement is the
+      dominant state. Any non-zero hmi is an artifact of isolated TF movement,
+      not genuine stack alignment.
+
+  IF regime = CONSOL
+    → Price is in compression. HMI will return near-zero or weakly directional
+      values that reflect historical TF drift, not current directional state.
+      Directional interpretation is not valid in this regime.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+
+  IF hmi >= 75 AND being used to assess reversal probability or overbought state
+    → INCORRECT USE. hmi measures stack alignment, not price extension.
+      Extreme hmi can persist for the duration of a strong trend.
+      FOR extension/reversal assessment: use indicators.weighted_rsi,
+      indicators.vwap_zscore, or indicators.bayesian_overbought instead.
+
+  IF hmi IN 15..40 AND hmi_velocity has not been evaluated
+    → INCOMPLETE EVALUATION. At this range, hmi cannot distinguish early-stage
+      momentum from fading momentum. The reading is structurally ambiguous.
+      Do not act until hmi_velocity confirms trajectory.
+
+  IF hmi reading is being used as overbought/oversold signal
+    → INCORRECT USE. High hmi ≠ overbought. Low hmi ≠ oversold.
+      These are independent constructs measuring different market dimensions.
+
+  IF activity_ratio < 0.8 AND hmi is large in magnitude
+    → HIGH FALSE-SIGNAL RISK. Below-normal volume is the most frequent source
+      of misleading hmi readings. The weighted sum can appear compelling while
+      being computed on thin flow. Apply confidence reduction proportional
+      to how far activity_ratio is below 0.8.
+
+  IF hmi is high AND representing a short-timeframe bounce against a multi-hour trend
+    → VERIFY: This scenario cannot produce high hmi by construction.
+      1m+3m+5m combined weight = 0.19. 1h alone = 0.16.
+      IF hmi IS high in this scenario, re-check that longer TF data is current
+      and not stale. A stale 1h reading in downtrend would cause exactly this
+      apparent contradiction.

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

@@ -0,0 +1,155 @@
+================================================================================
+INDICATOR: HMI_VELOCITY — HELIOS MOMENTUM INDEX VELOCITY
+================================================================================
+id:                 hmi_velocity
+data_field:         indicators.hmi_velocity
+type:               NUMERIC
+range:              Unbounded (practically constrained by parent HMI range of -100 to 100)
+precision:          2 decimal places
+update_rate:        per_tick
+latency_profile:    COINCIDENT
+                    # Measures rate of change of hmi at the current moment.
+                    # Always evaluate jointly with data_field: indicators.hmi
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+hmi_velocity is the first derivative of the composite HMI score, smoothed via
+exponential moving average. It is NOT the internal Kalman velocity state (x[1])
+used inside HMI's per-timeframe processing. It is computed as:
+
+  rawDelta = currentHmi - prevHmi
+  hmi_velocity = EMA(rawDelta, prevVelocity, alpha=0.15)
+  EMA formula: alpha * rawDelta + (1 - alpha) * prevVelocity
+
+The alpha of 0.15 produces significant smoothing — approximately 12 ticks of
+effective lag. This makes hmi_velocity a stable trend-of-trend signal, not a
+noisy tick-to-tick delta.
+
+hmi_velocity encodes:
+  SIGN       Whether HMI is currently rising (positive) or falling (negative)
+  MAGNITUDE  How fast the directional state is accelerating or decelerating
+
+A value of zero means HMI is holding steady. Positive means momentum alignment
+is strengthening. Negative means it is weakening or reversing.
+
+--------------------------------------------------------------------------------
+RANGE INTERPRETATION
+--------------------------------------------------------------------------------
+# Ranges are approximate due to unbounded nature — based on observed behavior
+# given parent HMI is clamped to [-100, 100] and EMA alpha is 0.15.
+
+  hmi_velocity >= 5.0
+    Sharp acceleration. HMI is gaining multiple points per tick on a sustained
+    basis. The timeframe stack is rapidly broadening alignment. Associated with
+    early-stage breakouts or momentum surges where shorter TFs are pulling the
+    composite upward quickly.
+
+  hmi_velocity >= 2.0 AND hmi_velocity < 5.0
+    Steady acceleration. HMI is climbing at a healthy pace. Alignment is building
+    across timeframes. Combines with moderate-to-high HMI for highest conviction
+    momentum states.
+
+  hmi_velocity >= 0.5 AND hmi_velocity < 2.0
+    Mild acceleration. HMI is trending upward slowly. May reflect gradual TF
+    stack alignment or stabilization after prior momentum. Not an entry signal
+    by itself.
+
+  hmi_velocity > -0.5 AND hmi_velocity < 0.5
+    Stable / no meaningful change. HMI is flat or barely moving. Current
+    alignment state is holding. No directional information from velocity alone.
+
+  hmi_velocity > -2.0 AND hmi_velocity <= -0.5
+    Mild deceleration. HMI is losing ground slowly. Momentum is fading.
+    Existing alignment is degrading. Monitor for continuation of deceleration.
+
+  hmi_velocity > -5.0 AND hmi_velocity <= -2.0
+    Steady deceleration. HMI is dropping at a meaningful pace. Timeframe stack
+    is diverging. High-hmi readings with this velocity should be treated as
+    lagging — the current state is weaker than hmi alone suggests.
+
+  hmi_velocity <= -5.0
+    Sharp deceleration. Rapid stack divergence in progress. If hmi is still
+    positive and high, the reading is substantially lagging. Associated with
+    exhaustion peaks, failed breakouts, or sudden reversal of alignment after
+    a squeeze break that rapidly fades.
+
+--------------------------------------------------------------------------------
+HMI DISAMBIGUATION TABLE
+--------------------------------------------------------------------------------
+# hmi IN 15..40 (and -40..-15 for downside) is structurally ambiguous without velocity.
+# This table resolves the ambiguity.
+
+  IF hmi >= 15 AND hmi < 40
+    IF hmi_velocity >= 2.0  → Building. Short-to-medium TFs are aligning.
+    IF hmi_velocity >= 0.0  → Holding. Stack is stable but not expanding.
+    IF hmi_velocity < 0.0   → Fading. Reading is trailing edge of alignment.
+                               Do not treat hmi value as current state.
+
+  IF hmi >= 60
+    IF hmi_velocity >= 0.0  → Continuation. Stack integrity intact.
+    IF hmi_velocity < -3.0  → Structural divergence. Value is lagging.
+                               Short TFs reversing while long TFs still positive.
+
+  IF hmi > -15 AND hmi < 15
+    → hmi_velocity has no directional meaning here.
+      Stack is not in consensus; velocity of a near-zero score is noise.
+
+  # Mirror these conditionals for negative hmi values with sign-inverted velocity.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.hmi | REQUIRED_COMPANION
+    hmi_velocity has no meaning without its parent hmi value.
+    hmi_velocity alone cannot indicate market direction.
+
+  indicators.regime | CONTEXT
+    IF regime IN [EXHAUST_UP, EXHAUST_DN] AND hmi_velocity confirms deceleration
+      → Regime and velocity agree on momentum peak. Higher confidence in
+         exhaustion read.
+    IF regime = BREAKOUT AND hmi_velocity >= 3.0
+      → Regime and velocity agree on acceleration. Breakout is expanding.
+    IF regime = CASCADE_UP AND hmi_velocity <= -3.0
+      → Conflict. Regime reflects established long-TF alignment (lagging).
+         Velocity is detecting early divergence. Monitor next few ticks.
+
+  indicators.tf_alignment | CONTEXT
+    Rising hmi_velocity with rising tf_alignment = alignment broadening.
+    Falling hmi_velocity with stable tf_alignment = magnitude shrinking
+    before breadth shrinks. Velocity leads tf_alignment at turns.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  hmi is the parent — if hmi is invalidated, discard hmi_velocity.
+  2  If hmi IN -15..15: hmi_velocity has no directional content.
+  3  Apply disambiguation table above for direction.
+  4  Cross-reference with regime if available.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF indicators.hmi is invalidated (see hmi.txt)
+    → hmi_velocity is also invalid. Discard.
+
+  IF hmi IN -5..5
+    → hmi_velocity carries no directional content. Do not use.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF hmi_velocity is evaluated without first reading hmi
+    → INCOMPLETE EVALUATION. hmi_velocity has no directional meaning in
+       isolation. Acceleration of a near-zero hmi is noise.
+
+  IF hmi_velocity > 0 is used as a long signal independently
+    → INCORRECT USE. hmi_velocity tells you the trajectory of the stack,
+       not whether the stack is currently aligned. Rising velocity from
+       hmi = -80 means downside momentum is becoming less severe, not
+       that a long entry is appropriate.
+
+  IF hmi_velocity is expected to flip simultaneously with hmi at a pivot
+    → INCORRECT EXPECTATION. alpha=0.15 produces ~12 tick smoothing lag.
+       Velocity will show prior direction for several ticks after hmi turns.
+       Prioritize hmi level change over velocity for turn detection.

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

@@ -0,0 +1,136 @@
+================================================================================
+INDICATOR: HURST_EXPONENT
+================================================================================
+id:                 hurst_exponent
+data_field:         indicators.hurst_exponent
+type:               NUMERIC
+range:              0.0 to 1.0
+precision:          3 decimal places
+update_rate:        per_tick (requires sufficient close price history)
+latency_profile:    SLOW — computed from rolling close price history using R/S analysis
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+The Hurst Exponent is computed via Rescaled Range (R/S) analysis on log returns
+from sequential 1m close prices.
+
+Computation:
+  returns[i] = closes[i] / closes[i-1] - 1   (for each consecutive close pair)
+  Minimum 16 valid returns required. If < 16: returns default value 0.5.
+
+  For window sizes w (powers of 2, from minWindow=8 to maxWindow=length/2):
+    Divide returns into floor(length/w) non-overlapping blocks.
+    For each block: compute mean, cumulative deviations, range, std dev.
+    R/S = range / std_dev for each block, then average across blocks.
+    Store (log(w), log(avgRS)) pair.
+
+  Hurst = slope of OLS linear regression on collected (log(w), log(avgRS)) pairs.
+  H = (k·Σxy - Σx·Σy) / (k·Σx² - (Σx)²)
+  Clamped to [0, 1].
+
+The exponent captures whether 1m close price returns exhibit autocorrelation
+(trending persistence) or anti-correlation (mean-reverting tendency).
+
+--------------------------------------------------------------------------------
+RANGE INTERPRETATION
+--------------------------------------------------------------------------------
+  value > 0.6
+    Persistent / trending. Returns are positively autocorrelated — up moves tend
+    to follow up moves, down moves follow down moves. Price has a statistical
+    tendency to continue in the current direction. Momentum strategies have
+    a statistical edge. The higher above 0.5, the stronger the persistence.
+
+  value >= 0.45 AND value <= 0.55 (approximately)
+    Random walk. Returns exhibit minimal autocorrelation. Price movement has no
+    detectable persistent or mean-reverting tendency at the 1m timeframe.
+    No statistical edge in either direction from this metric alone.
+
+  value < 0.4
+    Anti-persistent / mean-reverting. Returns are negatively autocorrelated — up
+    moves tend to follow down moves and vice versa. Price has a statistical
+    tendency to reverse rather than continue. Mean-reversion strategies have
+    a statistical edge. The lower below 0.5, the stronger the mean-reversion.
+
+  value < 0.3
+    Strong mean-reversion tendency. Price is exhibiting persistent countertrend
+    behavior at the 1m level. Fade setups may be favored over trend-following.
+
+  value = 0.5 (exactly)
+    Default value returned when insufficient close price history is available
+    (< 16 valid returns). Treat as UNKNOWN, not as a meaningful reading.
+
+--------------------------------------------------------------------------------
+IMPORTANT CONSTRAINTS ON USE
+--------------------------------------------------------------------------------
+# Hurst Exponent is a statistical property, not a real-time signal.
+# These constraints must be evaluated before use.
+
+  1. It is computed from 1m close prices only. It reflects behavior at the 1m
+     return level. It does not describe behavior at 1h or 4h timeframes.
+
+  2. It is a lagging statistical measure. A regime change or sudden shift in
+     price behavior will take many ticks to be reflected in Hurst.
+
+  3. It measures tendency, not certainty. H = 0.65 does not mean price will
+     continue in the current direction — it means historically over the
+     lookback window, returns have been positively autocorrelated.
+
+  4. When total history is exactly at the minimum threshold (16 returns),
+     the estimate is noisy. Reliable estimates require substantially more data.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.directional_efficiency | COMPANION
+    directional_efficiency measures current net movement cleanliness.
+    hurst_exponent measures historical return persistence.
+    IF hurst >= 0.6 AND directional_efficiency >= 0.5
+      → Current price movement is efficient AND historical pattern is trending.
+         Strongest case for momentum strategy applicability.
+    IF hurst < 0.4 AND directional_efficiency < 0.3
+      → Both current and historical measures indicate non-directional movement.
+         Mean-reversion strategies may be favored over momentum.
+
+  indicators.vwap_zscore | COMPANION FOR MEAN-REVERSION
+    IF hurst < 0.4 AND |vwap_zscore| > 2.0
+      → Historical mean-reverting tendency PLUS current price extended far
+         from VWAP. Both independently suggest mean-reversion probability.
+
+  indicators.regime | CONTEXT
+    TRENDING regimes (CASCADE, BREAKOUT, TREND) should co-occur with
+    hurst > 0.5 when the trend has persisted for sufficient time.
+    IF regime = CASCADE_UP AND hurst < 0.4:
+      → The trend may be very young (not yet reflected in Hurst) OR the
+         Hurst estimate is based on pre-trend history. Allow lag time for
+         Hurst to reflect new trend conditions.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  If value = 0.5 exactly: insufficient history; discard.
+  2  Read range interpretation.
+  3  Cross-validate with directional_efficiency and regime for context.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF value = 0.5 (default)
+    → Insufficient close price history. Reading is meaningless.
+
+  IF recent regime change occurred (< last 20 ticks)
+    → Hurst may still reflect prior regime. Do not treat as current state.
+       Allow 20-50 ticks for Hurst to converge after a regime shift.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF hurst > 0.6 is used to confirm a long entry independently
+    → INCOMPLETE USE. Hurst describes historical 1m return autocorrelation,
+       not current momentum direction. A high H on a downtrending asset means
+       the downtrend is persistent. Combine with direction indicators (hmi, regime).
+
+  IF hurst is expected to respond quickly to a new trend
+    → INCORRECT EXPECTATION. Hurst is a slow statistical indicator. It
+       requires many data points to converge on a new value. It lags real-time
+       regime changes significantly.