@pgnio/helios-mcp 0.2.7 → 0.2.9

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

@@ -1,115 +0,0 @@
-================================================================================
-INDICATOR: SQUEEZE_DURATION — VOLATILITY SQUEEZE DURATION
-================================================================================
-id:                 squeeze_duration
-data_field:         indicators.squeeze_duration
-type:               NUMERIC (integer count)
-range:              [0, ∞)
-precision:          Integer (whole number of ticks)
-update_rate:        per_tick
-latency_profile:    COINCIDENT
-
---------------------------------------------------------------------------------
-CONSTRUCT
---------------------------------------------------------------------------------
-squeeze_duration counts the number of consecutive ticks where the volatility
-squeeze value has been BELOW the squeeze threshold of 0.8.
-
-  IF indicators.volatility_squeeze < 0.8
-    squeeze_duration += 1
-  
-  IF indicators.volatility_squeeze >= 0.8
-    squeeze_duration = 0   (reset immediately when squeeze breaks)
-
-A duration of 0 means either the squeeze is not active (value >= 0.8) or
-the squeeze just started this tick (first tick below 0.8).
-
-This indicator quantifies the TIME dimension of the squeeze. When combined
-with volatility_squeeze (depth) and squeeze_energy (integrated depth × time),
-it provides the full picture of a squeeze development.
-
---------------------------------------------------------------------------------
-RANGE INTERPRETATION
---------------------------------------------------------------------------------
-  value = 0
-    No active squeeze. volatility_squeeze >= 0.8. Normal or expanding
-    volatility conditions. OR: squeeze just broke this tick (value resets
-    immediately). In either case: not in a sustained compression state.
-
-  value 1-5 (very short)
-    Just entered squeeze territory. Compression has barely begun.
-    Insufficient duration for meaningful energy buildup. Do not treat as
-    an active squeeze setup until duration is longer.
-
-  value 6-20 (short squeeze)
-    Squeeze has persisted for a meaningful period. Some directional energy
-    is building, especially if volatility_squeeze is also deep (< 0.5).
-    Combination of squeeze_duration and squeeze_energy now worth monitoring.
-
-  value 21-60 (moderate squeeze)
-    Sustained compression. An extended period of volatility below the GARCH
-    baseline. This duration at low squeeze_value produces significant squeeze_energy.
-    Market is in a genuine consolidation/coiling phase.
-
-  value > 60 (extended squeeze)
-    Prolonged compression. Very significant stored directional energy by any
-    measure. Extended squeezes historically precede the most significant
-    breakout moves. The asset has been unable to sustain any realized trend
-    for a long period.
-
---------------------------------------------------------------------------------
-INDICATOR RELATIONSHIPS
---------------------------------------------------------------------------------
-  indicators.volatility_squeeze | REQUIRED_COMPANION
-    squeeze_duration counts ticks at squeeze; but duration without
-    knowing the depth (volatility_squeeze value) is incomplete.
-    
-    High duration + deep squeeze = maximum energy accumulation.
-    High duration + shallow squeeze (value = 0.75) = moderate accumulation.
-    Low duration + deep squeeze = sudden sharp compression, not settled yet.
-
-    The most significant setups are:
-      volatility_squeeze < 0.4 AND squeeze_duration > 30
-
-  indicators.squeeze_energy | COMPANION
-    squeeze_energy = squeeze_duration × (0.8 - volatility_squeeze)
-    It is the integrated compression depth over time.
-    squeeze_duration is the COUNT; squeeze_energy is the MAGNITUDE.
-    Use duration to track progression; use energy for trade assessment.
-
-  indicators.regime | CONTEXT
-    IF regime = CONSOL AND squeeze_duration > 20
-      → Both regime and volatility confirm sustained compression.
-    IF regime shifts from CONSOL to BREAKOUT AND squeeze_duration was > 20
-      → The squeeze has been significant and the breakout is more likely
-         to produce a sustained move.
-
---------------------------------------------------------------------------------
-DEPENDENCY ORDER
---------------------------------------------------------------------------------
-  1  If squeeze_duration = 0: no active squeeze; no buildup to evaluate.
-  2  Read volatility_squeeze for current depth.
-  3  Read squeeze_energy for integrated depth × time.
-  4  Classify duration (short/moderate/extended) per ranges above.
-  5  Regime for compression/breakout context.
-
---------------------------------------------------------------------------------
-INVALIDATION CONDITIONS
---------------------------------------------------------------------------------
-  No specific invalidation beyond the parent volatility_squeeze indicator.
-  If volatility_squeeze is in warm-up (< 50 ticks since reset), squeeze_duration
-  may show extended values from the warm-up period. Treat as unreliable.
-
---------------------------------------------------------------------------------
-ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
---------------------------------------------------------------------------------
-  IF squeeze_duration > 60 is treated as urgency to enter a trade
-    → INCORRECT TIMING LOGIC. Long squeeze duration means energy has been
-       building — it does NOT tell you when the release will occur. A squeeze
-       can persist for 200+ ticks. Duration informs the MAGNITUDE of the
-       expected move when it occurs, not the TIMING.
-
-  IF squeeze_duration resets to 0 is missed and old duration is used
-    → DATA FRESHNESS CHECK REQUIRED. squeeze_duration resets immediately
-       when volatility_squeeze >= 0.8. If you are caching the prior reading,
-       you may be working with stale duration data. Always re-read per tick.

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

@@ -1,128 +0,0 @@
-================================================================================
-INDICATOR: SQUEEZE_ENERGY — VOLATILITY SQUEEZE ENERGY
-================================================================================
-id:                 squeeze_energy
-data_field:         indicators.squeeze_energy
-type:               NUMERIC
-range:              [0, ∞) — resets to 0 whenever squeeze breaks
-precision:          3 decimal places
-update_rate:        per_tick
-latency_profile:    COINCIDENT
-
---------------------------------------------------------------------------------
-CONSTRUCT
---------------------------------------------------------------------------------
-squeeze_energy is the integrated measure of volatility compression, capturing
-both HOW LONG and HOW DEEPLY the volatility has been squeezed. It combines the
-time (duration) and depth (compression magnitude) of the current squeeze.
-
-Formula (computed each tick while squeeze is active):
-  compressionDepth = 0.8 - indicators.volatility_squeeze
-    (positive only when volatility_squeeze < 0.8; deeper = larger value)
-
-  squeeze_energy = squeeze_duration × compressionDepth
-               = squeeze_duration × (0.8 - volatility_squeeze)
-
-  IF volatility_squeeze >= 0.8:
-    squeeze_energy = 0  (reset simultaneously with squeeze_duration)
-
-Examples:
-  - Duration=10, squeeze_value=0.5:  energy = 10 × 0.3  = 3.0
-  - Duration=30, squeeze_value=0.5:  energy = 30 × 0.3  = 9.0    (3× longer)
-  - Duration=10, squeeze_value=0.2:  energy = 10 × 0.6  = 6.0    (2× deeper)
-  - Duration=30, squeeze_value=0.2:  energy = 30 × 0.6  = 18.0   (most energy)
-
-squeeze_energy is the single best summary of "how much potential energy has built
-up in this squeeze". It is zero when no squeeze is active and grows as long as
-the squeeze persists.
-
---------------------------------------------------------------------------------
-RANGE INTERPRETATION
---------------------------------------------------------------------------------
-  value = 0
-    No active squeeze OR squeeze just started. No meaningful energy accumulation.
-
-  value 0.1 - 3.0
-    Low energy. Short and/or shallow squeeze. Potential move is not yet
-    significant by historical comparison. Continue monitoring.
-
-  value 3.0 - 10.0
-    Moderate energy. Sufficient compression has built to support a meaningful
-    directional breakout when it occurs. This band represents most "ready to
-    break" squeeze setups.
-
-  value 10.0 - 25.0
-    High energy. Significant compression over extended duration and/or depth.
-    The breakout when it occurs is more likely to produce an outsized move.
-    This is an alert-level condition.
-
-  value > 25.0
-    Very high energy. Extreme sustained compression. Very rare in normal markets.
-    When seen, the eventual breakout should be expected to be substantial.
-    Activity_ratio and volume_change_point conditions at release are key.
-
---------------------------------------------------------------------------------
-INDICATOR RELATIONSHIPS
---------------------------------------------------------------------------------
-  indicators.volatility_squeeze | REQUIRED_COMPANION
-    squeeze_energy is derived from volatility_squeeze depth.
-    Always verify volatility_squeeze is in squeeze state (< 0.8) alongside
-    any positive squeeze_energy reading.
-
-  indicators.squeeze_duration | COMPANION
-    Together with squeeze_duration, these three indicators form the complete
-    squeeze picture:
-      volatility_squeeze = current depth (real-time)
-      squeeze_duration   = time in compression (tick count)
-      squeeze_energy     = integrated depth × time (summary measure)
-
-  indicators.volume_change_point | ALERT COMPANION
-    When squeeze_energy is high AND volume_change_point.changePointProbability
-    is rising, it signals that the volume regime may be shifting — potentially
-    the initiation of the squeeze release. High energy + volume regime shift
-    is the most actionable combination.
-
-  indicators.market_structure | CONTEXT
-    IF squeeze_energy > 10 AND market_structure transitions to BREAKING_UP
-    or BREAKING_DOWN → the breakout is coming from a high-energy compressed
-    state. Highest conviction continuation expected.
-
-  indicators.hmi | POST-SQUEEZE DIRECTION
-    After squeeze_energy resets to 0 (squeeze broke), read hmi to determine
-    which direction the energy released in. This is the critical post-squeeze
-    directional inference step.
-
-  indicators.activity_ratio | TRIGGER COMPANION
-    IF squeeze_energy > 10 AND activity_ratio transitions from MODERATE/DEAD
-    to ACTIVE → new volume entering a compressed market. This is the most
-    common trigger for a squeeze release.
-
---------------------------------------------------------------------------------
-DEPENDENCY ORDER
---------------------------------------------------------------------------------
-  1  If squeeze_energy = 0: no active squeeze; no energy has accumulated.
-  2  Read volatility_squeeze for current depth.
-  3  Read squeeze_duration for elapsed time.
-  4  Classify energy level per ranges above.
-  5  Monitor volume_change_point for rising changepoint probability.
-  6  Post-reset (squeeze broke): read hmi for direction of energy release.
-
---------------------------------------------------------------------------------
-INVALIDATION CONDITIONS
---------------------------------------------------------------------------------
-  All invalidations from volatility_squeeze apply.
-  IF volatility_squeeze is in warm-up: squeeze_energy from that period is
-  unreliable.
-
---------------------------------------------------------------------------------
-ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
---------------------------------------------------------------------------------
-  IF high squeeze_energy is used as a directional indicator
-    → INCORRECT. squeeze_energy tells you that a move is more likely to
-       be large when it comes. It says nothing about direction.
-       Only post-release hmi and regime provide direction.
-
-  IF squeeze_energy is monitored but release detection is missed
-    → WATCH FOR RESET. When squeeze_energy drops from a high value to 0,
-       the squeeze has broken. The next readings of hmi and regime provide
-       the directional interpretation of the released energy.

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

@@ -1,165 +0,0 @@
-================================================================================
-INDICATOR: TF_ALIGNMENT — TIMEFRAME ALIGNMENT SCORE
-================================================================================
-id:                 tf_alignment
-data_field:         indicators.tf_alignment
-type:               NUMERIC
-range:              0.0 to 100.0
-precision:          1 decimal place
-update_rate:        per_tick
-latency_profile:    COINCIDENT
-
---------------------------------------------------------------------------------
-CONSTRUCT
---------------------------------------------------------------------------------
-tf_alignment measures what percentage of short-term timeframe momentum is moving
-in the same direction as the macro (longer-term) trend.
-
-Computation:
-  STEP 1: Determine macro direction using 4h, 6h, 8h, 12h, 24h changes only.
-          macroDir = sign(sum of those 5 TF changes) ∈ {-1, 0, 1}
-
-  STEP 2: For each short TF [1m, 3m, 5m, 15m, 30m, 1h, 2h], compute the
-          magnitude-weighted contribution toward or against macroDir.
-
-  Weights applied per TF (decaying):
-    1m: 1.00  |  3m: 0.95  |  5m: 0.90  |  15m: 0.85
-    30m: 0.80 |  1h: 0.75  |  2h: 0.65
-
-  For each short TF:
-    contribution = |change| × weight
-    IF sign(change) == macroDir: adds to alignedWeight
-    always adds to totalWeight
-
-  value = (alignedWeight / totalWeight) × 100
-
-Special case: IF all short TFs are near zero (totalWeight ≈ 0):
-  Fall back to sign-agreement count rather than magnitude weighting.
-
-tf_alignment specifically measures whether SHORTER timeframes (1m–2h) are
-agreeing with the LONGER timeframe direction (4h–24h). It does NOT measure
-whether all 12 TFs agree with each other.
-
-A value of 100 means every short TF is moving in the same direction as the
-macro trend. A value of 0 means every short TF is moving against the macro.
-A value of 50 means perfectly split.
-
---------------------------------------------------------------------------------
-RANGE INTERPRETATION
---------------------------------------------------------------------------------
-  value > 85
-    Extreme alignment. Every short timeframe contribution is directionally
-    consistent with macro. Short-TF price action is fully confirming the
-    longer-term trend. Historically associated with CASCADE and BREAKOUT
-    regimes. Maximum breadth state.
-
-  value > 70 AND value <= 85
-    High alignment. Most short-TF magnitude agrees with macro. The trend
-    has broad participation from intraday timeframes. Strong confirmation
-    of macro direction from the shorter stack.
-
-  value > 55 AND value <= 70
-    Moderate alignment. Majority of short-TF weight is directionally aligned,
-    but meaningful dissent exists. Some shorter TFs are countertrending.
-    Likely reflects normal pullbacks or consolidation within an established trend.
-
-  value > 40 AND value <= 55
-    Low alignment. Roughly split between short TFs agreeing and disagreeing
-    with macro. Directional inference is unreliable. The short-TF stack is
-    not confirming OR refuting the macro trend.
-
-  value <= 40
-    Divergence. The short-TF stack is predominantly moving AGAINST the macro
-    direction. This can represent:
-      - A reversal forming at the short-TF level
-      - A countertrend move before macro reasserts
-      - Transition period between regimes
-    Do not use macro-aligned directional signals during this state.
-
---------------------------------------------------------------------------------
-TRAJECTORY — RATE OF CHANGE
---------------------------------------------------------------------------------
-# tf_alignment does not have its own velocity field in the data feed.
-# Assess trajectory by comparing consecutive readings or using hmi_velocity
-# as a proxy (they tend to move together at turns).
-
-  Rising tf_alignment (→ recent readings higher than prior)
-    Short TFs are converging toward macro direction.
-    Alignment is broadening. Associated with momentum building.
-
-  Falling tf_alignment (→ recent readings lower than prior)
-    Short TFs are diverging from macro direction.
-    Alignment is narrowing. Associated with momentum fading or pullback.
-
-  tf_alignment < 50 while hmi is still positive
-    Short TFs have turned against macro. HMI is lagging.
-    The current HMI value overstates current alignment state.
-
---------------------------------------------------------------------------------
-INDICATOR RELATIONSHIPS
---------------------------------------------------------------------------------
-  indicators.hmi | AMPLIFIES
-    tf_alignment measures breadth; hmi measures magnitude.
-    These are different but complementary dimensions of the same stack.
-
-    IF hmi >= 60 AND tf_alignment >= 80
-      → Maximum signal quality. Both magnitude and breadth confirm direction.
-
-    IF hmi >= 60 AND tf_alignment < 50
-      → HMI has high weighted sum but short TFs are not broadly aligned.
-         The high magnitude is concentrated — likely the 1h/2h TFs are
-         dominant while others are flat or opposing. Reduce confidence.
-
-    IF hmi < 30 AND tf_alignment > 70
-      → High breadth but low magnitude. Many TFs agree on direction but
-         none have meaningful momentum yet. Low-energy directional state.
-
-  indicators.regime | CROSS_VALIDATE
-    CASCADE and BREAKOUT regimes imply tf_alignment should be >= 70.
-    IF regime = CASCADE_UP AND tf_alignment < 55:
-      → Data may be stale or the regime transition just occurred.
-         Monitor for convergence.
-
-    IF regime = CHOP AND tf_alignment is near 50:
-      → Expected. Both indicators consistently reflect disagreement.
-
-  indicators.directional_efficiency | COMPANION
-    tf_alignment measures directional breadth relative to macro.
-    directional_efficiency measures how cleanly price is moving in one
-    direction (low noise). They are complementary: high alignment +
-    high efficiency = strongest trending signal.
-
---------------------------------------------------------------------------------
-DEPENDENCY ORDER
---------------------------------------------------------------------------------
-  1  Regime: if CHOP/CONSOL/RANGING, macro direction is undefined; tf_alignment
-     near 50 is expected and uninformative.
-  2  Read value and range bucket.
-  3  Cross-validate with hmi for magnitude-breadth divergence.
-  4  Assess recent trajectory (rising vs falling alignment) if consecutive
-     readings are available.
-
---------------------------------------------------------------------------------
-INVALIDATION CONDITIONS
---------------------------------------------------------------------------------
-  IF regime = CHOP
-    → macroDir is undefined (sum of 4h-24h changes is near zero).
-      tf_alignment near 50 is expected and uninformative.
-
-  IF all TF changes are near zero (very low volatility / illiquid period)
-    → Magnitude weighting collapses to sign agreement. Result is noisy.
-      Cross-check with activity_ratio. If activity_ratio < 0.5: discard.
-
---------------------------------------------------------------------------------
-ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
---------------------------------------------------------------------------------
-  IF tf_alignment is used as a standalone direction signal
-    → INCORRECT USE. tf_alignment measures alignment WITH macro direction.
-       It cannot tell you what macro direction is. You must know macroDir
-       (from the 4h-24h cluster) separately before interpreting alignment
-       as bullish or bearish context.
-
-  IF tf_alignment of 80% is interpreted as "80% of timeframes are positive"
-    → INCORRECT INTERPRETATION. The percentage is MAGNITUDE-WEIGHTED alignment
-       with macro — not a head count of positive timeframes. A single 1h TF
-       with high magnitude can dominate the weighted result.

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

@@ -1,169 +0,0 @@
-================================================================================
-INDICATOR: VOLATILITY_SQUEEZE — GARCH VOLATILITY RATIO (SQUEEZE)
-================================================================================
-id:                 volatility_squeeze
-data_field:         indicators.volatility_squeeze
-type:               NUMERIC
-range:              [0, ∞) — practically [0.1, 1.5] in most conditions
-precision:          3 decimal places
-update_rate:        per_tick
-latency_profile:    COINCIDENT
-
---------------------------------------------------------------------------------
-CONSTRUCT
---------------------------------------------------------------------------------
-volatility_squeeze measures the ratio of short-window to long-window GARCH
-conditional volatility. It detects when volatility has compressed below historical
-norms (a "squeeze") — indicating stored directional energy.
-
-GARCH(1,1) model:
-  omega   = 0.00001
-  alpha   = 0.10     (weight on recent squared return)
-  beta    = 0.88     (weight on prior conditional variance)
-  h[t]    = omega + alpha × r[t-1]² + beta × h[t-1]
-  where r[t] = log return at time t
-
-Two GARCH variance series computed:
-  short_window = 14 ticks  →  h_short (14-period GARCH conditional variance)
-  long_window  = 50 ticks  →  h_long  (50-period GARCH conditional variance)
-
-Ratio:
-  value = sqrt(h_short / h_long)
-
-This ratio compares current short-term GARCH volatility to the recent long-term
-GARCH baseline. A value of 1.0 means current volatility is at its long-run norm.
-
-CRITICAL: LOWER VALUES MEAN MORE COMPRESSION (MORE ENERGY STORED)
-  value < 0.8   →  SHORT_TERM VOLATILITY IS COMPRESSED BELOW BASELINE
-  value >= 0.8  →  NORMAL OR EXPANDING VOLATILITY
-
---------------------------------------------------------------------------------
-RANGE INTERPRETATION — SQUEEZE STATES (BELOW 0.8)
---------------------------------------------------------------------------------
-  IMPORTANT: These are SQUEEZE conditions. The LOWER the value, the more
-  compressed the volatility. This is counterintuitive: a "lower squeeze value"
-  means MORE stored energy, not less.
-
-  value < 0.3  [EXTREME SQUEEZE]
-    Short-term GARCH volatility is less than 30% of the long-term norm.
-    Maximum compression. Historical breakouts after extreme squeeze are
-    often the most violent, as stored directional energy releases suddenly.
-    squeeze_duration and squeeze_energy will be at high values here.
-
-  value >= 0.3 AND value < 0.4  [ACTIVE SQUEEZE]
-    Short-term volatility is severely compressed. Still very significant
-    energy buildup. Price is in a tight consolidation with little realized
-    volatility. The market is coiling before a move.
-
-  value >= 0.4 AND value < 0.6  [MILD-ACTIVE SQUEEZE]
-    Meaningful compression. Volatility is building toward normal levels.
-    Not extreme but notable — this level typically precedes larger moves.
-
-  value >= 0.6 AND value < 0.8  [MILD SQUEEZE]
-    Light compression. Volume and volatility are slightly below the baseline.
-    Pre-squeeze signal or normal pullback in oscillation.
-
-  value >= 0.8  [EXPANSION / NO SQUEEZE]
-    Short-term volatility at or above its long-term GARCH norm. This is the
-    normal or expanding state. Price is realizing its typical or above-typical
-    movement. No stored energy condition.
-
-  value >> 1.0 (significantly above 1.0)
-    Current volatility is substantially above the long-run GARCH baseline.
-    Post-squeeze expansion or a volatility shock event.
-
---------------------------------------------------------------------------------
-TRAJECTORY MATTERS
---------------------------------------------------------------------------------
-# The direction of squeeze_value change is as important as the absolute level.
-
-  value moving from 0.8 → 0.5 → 0.3 (declining over multiple ticks)
-    Active compression building. Energy is accumulating. The lower it gets
-    and the longer it stays low, the more likely the breakout is material.
-    Monitor squeeze_duration and squeeze_energy for quantified buildup.
-
-  value moving from 0.3 → 0.6 → 0.9 (rising after a squeeze)
-    Squeeze is RELEASING. Energy is being converted to realized movement.
-    This is the expected transition AFTER the breakout move initiates.
-    By the time value is above 0.8, the acute breakout phase has begun.
-
-  value hovering near 0.5 for many ticks
-    Prolonged squeeze. Market is in sustained compression. Combined with
-    low squeeze_energy increase, this may indicate an information void
-    period. High-conviction break likely when catalyst arrives.
-
---------------------------------------------------------------------------------
-INDICATOR RELATIONSHIPS
---------------------------------------------------------------------------------
-  indicators.squeeze_duration | REQUIRED_COMPANION
-    squeeze_duration counts consecutive ticks where value < 0.8.
-    Low squeeze_value + high squeeze_duration = sustained compression.
-    The combination is more meaningful than either alone.
-
-  indicators.squeeze_energy | REQUIRED_COMPANION
-    squeeze_energy = squeeze_duration × (0.8 - value) = compressionDepth × time.
-    This is the integrated measure of compression buildup.
-    High squeeze_energy = the most significant potential release.
-
-  indicators.regime | CONTEXT
-    IF regime = CONSOL AND volatility_squeeze < 0.5
-      → Regime confirms consolidation AND volatility confirms compression.
-         Dual confirmation of coiling condition.
-    IF volatility_squeeze transitions above 0.8 AND regime shifts to BREAKOUT
-      → The squeeze is releasing AND regime has confirmed direction.
-         Highest confidence breakout signal.
-
-  indicators.market_structure | CONTEXT
-    market_structure = CONSOL or BREAKING_UP after a squeeze period confirms
-    the structural context of both compression and release.
-
-  indicators.activity_ratio | CONTEXT
-    IF activity_ratio < 0.5 AND volatility_squeeze < 0.5
-      → Compression in both volume AND GARCH volatility. Not just a quiet
-         period — both volume and price movement are compressed simultaneously.
-
-  indicators.hmi | CONTEXT
-    After a squeeze release, the direction of the hmi move (positive or negative)
-    provides the directional interpretation of the energy release.
-    volatility_squeeze confirms compression existed; hmi tells you which way
-    the energy released.
-
---------------------------------------------------------------------------------
-DEPENDENCY ORDER
---------------------------------------------------------------------------------
-  1  Read value; classify SQUEEZE (< 0.8) vs EXPANSION (>= 0.8).
-  2  In squeeze: classify depth (EXTREME < 0.3, ACTIVE < 0.4, MILD < 0.6).
-  3  Read squeeze_duration and squeeze_energy for magnitude of buildup.
-  4  Regime for compression/breakout confirmation.
-  5  Post-release: read hmi for direction of energy release.
-
---------------------------------------------------------------------------------
-INVALIDATION CONDITIONS
---------------------------------------------------------------------------------
-  IF fewer than 50 ticks of return history
-    → Long GARCH window (50) has not converged. Value is unreliable.
-       Treat first 50-60 ticks after start/reset as warm-up.
-
-  IF a sudden extreme price move occurs (> 5% in 1 tick)
-    → GARCH may spike sharply. One outlier return inflates h_short significantly.
-       Value may jump to >> 1.0 transiently. Wait for GARCH to stabilize.
-
---------------------------------------------------------------------------------
-ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
---------------------------------------------------------------------------------
-  IF value < 0.3 is treated as a trade signal on its own
-    → INCORRECT. Extreme squeeze tells you compression exists but says
-       NOTHING about direction. Directional confirmation (hmi, regime shift,
-       market_structure breakout) is required before acting.
-
-  IF value > 0.8 is treated as "safe to trade"
-    → INCORRECT INTERPRETATION. Value > 0.8 means volatility is expanding.
-       This is the RELEASE phase of a squeeze — often the most volatile
-       and fastest-moving period. This is when positions face highest
-       whipsaw risk, not least.
-
-  IF the relationship between value and compression is treated as "higher = more squeeze"
-    → INVERTING THE SCALE. Lower value = more compressed. value = 0.2
-       is maximum squeeze, NOT a minimum. This is a common error with
-       ratio-based indicators. Remember: value compares short GARCH to
-       long GARCH — below 1.0 means short is below long.