@pgnio/helios-mcp 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,134 @@
+================================================================================
+INDICATOR: TREND_STRENGTH
+================================================================================
+id:                 trend_strength
+data_field:         indicators.trend_strength
+type:               NUMERIC
+range:              0.0 to 100.0
+precision:          1 decimal place
+update_rate:        per_tick
+latency_profile:    COINCIDENT
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+trend_strength measures how strongly price is moving in a single direction
+across all timeframes, using a directional index (DX) approach similar to the
+ADX construction but applied to a multi-timeframe weighted framework.
+
+For each timeframe, directional components are computed:
+  posSum = sum of positive (upward) normalized changes across TFs
+  negSum = sum of |negative| (downward) normalized changes across TFs
+
+Cluster weights applied to normalize contribution:
+  micro [1m, 3m, 5m]      : weight = 1.00
+  short [15m, 30m, 1h]    : weight = 0.85
+  medium [2h, 4h, 6h]     : weight = 0.70
+  macro [8h, 12h, 24h]    : weight = 0.55
+
+DX formula:
+  diPlus   = (posSum / totalAbs) × 100
+  diMinus  = (negSum / totalAbs) × 100
+  dx       = (|diPlus - diMinus| / (diPlus + diMinus)) × 100
+  value    = dx (clamped to [0, 100])
+
+A value of 100 means ALL movement is in ONE direction (perfect trending).
+A value of 0 means equal amounts of upward and downward movement (perfect chop).
+trend_strength does NOT encode direction — only the magnitude of directional bias.
+Use in conjunction with hmi or regime to determine which direction is trending.
+
+--------------------------------------------------------------------------------
+RANGE INTERPRETATION
+--------------------------------------------------------------------------------
+  value >= 60
+    Strong trending. The directional imbalance is significant — substantially
+    more movement is in one direction than the other, weighted across all TF
+    clusters. The current directional bias is well-established and broad.
+
+  value >= 40 AND value < 60
+    Moderate trending. A meaningful directional imbalance exists but is not
+    extreme. Some timeframes may be countertrending while the majority confirms
+    direction. Trading with the trend has a statistical edge but with noise.
+
+  value >= 20 AND value < 40
+    Weak trending. Minor directional imbalance. The market has SOME bias
+    but it is faint. Countertrend activity is significant. Not reliable for
+    directional entries.
+
+  value < 20
+    Ranging / choppy. Near-equal amounts of upward and downward movement across
+    timeframes. No meaningful directional bias. Equivalent to CHOP regime signal.
+    Directional indicators carry no reliable information in this state.
+
+--------------------------------------------------------------------------------
+NOTE: RELATIONSHIP TO TREND_INTERPRETATION
+--------------------------------------------------------------------------------
+# indicators.trend_interpretation is a categorical version of this same value
+# derived from the same computation with the same thresholds:
+#   trend_strength >= 60  → STRONG
+#   trend_strength >= 40  → MODERATE
+#   trend_strength >= 20  → WEAK
+#   trend_strength < 20   → RANGING_CHOPPY
+# Use trend_strength for numeric comparisons; trend_interpretation for categorical logic.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.trend_interpretation | SAME DATA
+    trend_interpretation is a categorical label derived from this value.
+    They always agree. Use trend_strength for thresholds; trend_interpretation
+    for state-based branching (see trend_interpretation.txt).
+
+  indicators.hmi | CONTEXT
+    hmi provides directional sign; trend_strength provides magnitude quality.
+
+    IF hmi >= 60 AND trend_strength >= 60
+      → High magnitude AND high strength. Both indicators confirm a strong
+         directional move is underway. Highest quality trending signal.
+
+    IF hmi >= 40 AND trend_strength < 20
+      → HMI shows momentum but trend_strength shows equal countertrend noise.
+         The hmi reading may be driven by a few dominant TFs while the rest
+         are not confirming. Lower confidence.
+
+  indicators.directional_efficiency | COMPANION
+    directional_efficiency measures net/total ratio (cleanliness of price).
+    trend_strength measures directional imbalance (dominance of one direction).
+    These typically agree but can diverge during low-liquidity periods.
+
+  indicators.regime | CONTEXT
+    CHOP and RANGING regimes imply trend_strength < 20.
+    TREND and CASCADE regimes imply trend_strength >= 40-60.
+    Divergence between these should prompt recency check.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Regime: CHOP/CONSOL/RANGING confirms near-zero trend_strength is expected.
+  2  Read value and range bucket.
+  3  Read hmi or regime to determine the direction in which trend_strength applies.
+  4  Strong directional condition: trend_strength >= 40 AND |hmi| >= 30.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF activity_ratio < 0.5
+    → Volume is dead. TF changes are noise. trend_strength is unreliable.
+
+  IF value = 0 exactly
+    → Either totalAbs = 0 (no movement at all) or perfect balance.
+      Check activity_ratio to distinguish.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF trend_strength >= 60 is used as a direction signal
+    → INCORRECT USE. trend_strength has no direction component. A value
+       of 80 means strong directional bias exists, but it is equally
+       compatible with strong upward or strong downward bias. Always
+       combine with hmi or regime to determine direction.
+
+  IF trend_strength < 20 is used to say "no trend, so mean-revert"
+    → INCOMPLETE LOGIC. Low trend_strength means equal buy/sell pressure —
+       it does not predict where price will mean-revert to. Add vwap_zscore
+       and support/resistance to identify potential reversion targets.

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

@@ -0,0 +1,142 @@
+================================================================================
+INDICATOR: VALUE_AREA_POSITION — VALUE AREA POSITION
+================================================================================
+id:                 value_area_position
+data_field:         indicators.value_area_position
+type:               CATEGORICAL
+values:             ABOVE VA | IN VA | BELOW VA
+update_rate:        per_tick
+latency_profile:    SLOW (computed from volume profile history)
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+value_area_position classifies where the current price is relative to the
+Value Area — the price range that contained 70% of all traded volume over
+the observation window.
+
+Value Area Computation (derived from the same volume profile as POC):
+  1. Start at POC bucket (highest volume).
+  2. Greedily expand upward or downward, adding one bucket at a time in the
+     direction that adds more volume, until cumulative volume >= 70% of total.
+  3. value_area_high = upper edge of the final Value Area.
+  4. value_area_low  = lower edge of the final Value Area.
+
+Classification:
+  ABOVE VA: currentPrice > value_area_high
+  IN VA:    currentPrice >= value_area_low AND <= value_area_high
+  BELOW VA: currentPrice < value_area_low
+
+Related data fields:
+  indicators.value_area_high  (price level)
+  indicators.value_area_low   (price level)
+  indicators.poc              (highest-volume level within or determining the VA)
+
+--------------------------------------------------------------------------------
+STATE DEFINITIONS
+--------------------------------------------------------------------------------
+  IN VA
+    Price is trading within the 70% volume zone. This zone represents where
+    the majority of participating market actors transacted. Price "in VA" is
+    in a high-liquidity, high-familiarity zone. Breakouts from VA often require
+    significant volume to sustain.
+
+    Within VA, the POC acts as a sub-anchor. Price typically gravitates toward
+    POC when in-range before committing to test one of the VA edges (VA_High
+    or VA_Low).
+
+  ABOVE VA
+    Price has moved above the zone where 70% of volume transacted. This is
+    "price discovery" territory relative to recent volume distribution.
+    Less support from historical buyers in this zone.
+
+    ABOVE VA as BEARISH CONTEXT (value-area mean-reversion):
+      If regime is not trending, ABOVE VA suggests price is extended beyond
+      typical range and may be subject to pull-back into the area.
+
+    ABOVE VA as BULLISH CONTEXT (breakout continuation):
+      In trending/breakout regimes with volume confirmation, ABOVE VA is
+      continuation — price is leaving the old range. New value area will form
+      at higher levels.
+
+  BELOW VA
+    Mirror of ABOVE VA. Price is below the 70% volume zone.
+
+    BELOW VA as BULLISH CONTEXT (mean-reversion):
+      Potential recovery toward VA from the low side in non-trending regimes.
+
+    BELOW VA as BEARISH CONTEXT (breakdown continuation):
+      In trending/breakdown regimes, BELOW VA confirms price has broken
+      below the old value area and is discovering new lower prices.
+
+--------------------------------------------------------------------------------
+REGIME CONTEXT
+--------------------------------------------------------------------------------
+# The same VA position has opposite implications depending on regime.
+
+  ABOVE VA + regime IN [CHOP, CONSOL, RANGING]
+    Price is extended above the value distribution in a non-trending state.
+    Mean-reversion toward IN VA is the historically prevalent outcome.
+
+  ABOVE VA + regime IN [CASCADE, PARABOLIC, BREAKOUT]
+    Price has left the prior value area in a trending state.
+    New VA is forming at higher levels; extension is continuation context.
+
+  ABOVE VA + regime = EXHAUST_UP
+    Extended above VA with decelerating momentum.
+    Highest compound mean-reversion risk in a post-breakout context.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.poc_distance | COMPANION
+    value_area_position gives the coarse zone (above/in/below VA).
+    poc_distance gives the precise distance from the highest-volume node.
+    Use both for complete volume-profile positioning.
+
+  indicators.poc | PREREQUISITE
+    poc is computed first; VA expands from poc. They always move together.
+    When VA is wide, poc_distance and value_area_position may disagree
+    slightly (price can be IN VA but far from poc if VA is large).
+
+  indicators.regime | REQUIRED CONTEXT
+    Do not use value_area_position for directional inference without regime.
+    The same state (ABOVE VA) is bullish in a breakout and bearish in a
+    choppy market. See regime gate above.
+
+  indicators.vwap_zscore | COMPOUND SIGNAL
+    IF value_area_position = ABOVE VA AND vwap_zscore > 2.0
+      → Price above VWAP AND outside value area on the upside. Both
+         volume-anchored references agree on extension.
+
+  indicators.support / indicators.resistance | CONTEXT
+    value_area_high / value_area_low are implicit support/resistance levels.
+    When the explicit resistance indicator also shows a strong level near
+    value_area_high, that level has dual anchoring.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Read regime — determines whether ABOVE/BELOW VA is extension or continuation context.
+  2  Read value_area_position.
+  3  If not IN VA: read poc_distance for exact deviation magnitude.
+  4  Read value_area_high / value_area_low as specific price levels.
+  5  Cross-reference with vwap_zscore.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF insufficient candle history: value area cannot be computed.
+
+  IF totalVol == 0 (no volume data): computation fails. Do not use.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF ABOVE VA is treated as a short signal without regime check
+    → INCORRECT. See regime interpretation section above. Context determines
+       whether ABOVE VA is bearish extension or bullish breakout confirmation.
+
+  IF value_area_position is used without referencing the price levels
+    → INCOMPLETE. "ABOVE VA" without knowing where value_area_high is
+       numerically prevents referencing it as a level. Read the price levels too.

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

@@ -0,0 +1,160 @@
+================================================================================
+INDICATOR: VOLATILITY_CLUSTERING — VOLUME CLUSTERING MULTIPLIER
+================================================================================
+id:                 volatility_clustering
+data_field:         indicators.volatility_clustering
+type:               NUMERIC (+ embedded sub-field)
+range:              [0.7, 1.5]
+                    !! NOT [0, 1] — this is a common documentation error !!
+precision:          3 decimal places
+update_rate:        per_tick
+latency_profile:    LAGGING (computed from 6 timeframe volume z-scores)
+
+EMBEDDED FIELD:
+  indicators.volatility_clustering.change_point_probability
+  type:   NUMERIC
+  range:  [0, 1]
+  See: volume_change_point.txt for detailed documentation of this sub-field.
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+volatility_clustering measures whether current volume activity is above or below
+the historical norm across multiple timeframes, expressed as a confidence
+multiplier. A value above 1.0 means above-normal volume clustering; below 1.0
+means below-normal.
+
+Computation:
+  For each of 6 timeframes: [5m, 15m, 30m, 1h, 4h, 12h]
+    - Compute z-score of log(volume) vs 3× timeframe lookback baseline:
+        z[tf] = (log(currentVol_tf) - mean(logVols_tf)) / std(logVols_tf)
+    - Compute per-TF multiplier:
+        multiplier_tf = clamp(1.0 + z[tf] × 0.15, 0.7, 1.5)
+
+  Weighted combination across 6 TFs (higher TFs weighted more for stability).
+
+  Final value = weighted average of multiplier_tf values.
+
+Scale:
+  1.0  = neutral (volume at exactly historical norm)
+  < 1.0  = below-normal volume clustering (minimum: 0.7)
+  > 1.0  = above-normal volume clustering (maximum: 1.5)
+
+--------------------------------------------------------------------------------
+RANGE INTERPRETATION
+--------------------------------------------------------------------------------
+  value >= 1.3
+    Significantly above-normal volume clustering. Volume across multiple TFs
+    is substantially higher than the historical baseline. Associated with
+    high-participation conditions: breakouts, major news reactions, capitulation.
+    This is when price moves are most likely to sustain.
+
+  value >= 1.1 AND value < 1.3
+    Moderately elevated volume. Above historical norm with some confidence.
+    Activity is picking up across TFs. Directional signals are more reliable
+    in this condition.
+
+  value >= 0.9 AND value < 1.1
+    Near-normal volume activity. Close to baseline. Volume is neither
+    confirming nor calling into question directional signals.
+
+  value >= 0.7 AND value < 0.9
+    Below-normal volume clustering. Activity is quieter than the historical
+    baseline. Directional signals from momentum indicators have reduced
+    reliability. Spreads may be wider; price moves less committed.
+
+  value = 0.7 (at minimum clamp)
+    Volume is at maximum below-normal (floored). Very quiet market across
+    multiple timeframes. Functionally equivalent to activity_ratio being DEAD.
+    Most indicators should be treated with skepticism here.
+
+IMPORTANT CORRECTION vs HUMAN DOCS:
+  The human-readable documentation incorrectly stated this range as [0, 1].
+  The actual computation clamps per-TF multipliers to [0.7, 1.5] and takes
+  a weighted average, so the output is also strictly within [0.7, 1.5].
+  A value of 0.0 or 0.5 is NOT possible from this indicator.
+
+--------------------------------------------------------------------------------
+ROLE AS THRESHOLD MODULATOR
+--------------------------------------------------------------------------------
+# volatility_clustering acts as a confidence multiplier for several indicators.
+# Its most important direct use is in vwap_zscore threshold adjustment.
+
+  vwap_zscore bands are internally scaled by volcMultiplier:
+    In high-clustering periods (value = 1.4): z-score bands widen.
+    In low-clustering periods (value = 0.75): z-score bands compress.
+    This means FAR_ABOVE requires a LARGER z-score to qualify when
+    volume clustering is high.
+
+  General confidence relationship:
+    volatility_clustering < 0.85  → below-normal participation; all signals noisier.
+    volatility_clustering > 1.20  → above-normal participation; signals more reliable.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.activity_ratio | COMPANION
+    Both measure volume activity relative to baseline, but via different methods.
+    activity_ratio: 5-candle recent vs 1-day time-of-day normalized baseline.
+    volatility_clustering: log z-score across 6 TFs vs 3× TF lookback.
+
+    They may diverge:
+      IF activity_ratio = ACTIVE AND volatility_clustering < 0.9
+        → Current 5-candle window is active but the multi-TF clustering is below
+           norm. A short-term volume spike, not a sustained participation increase.
+      IF activity_ratio = DEAD AND volatility_clustering >= 1.1
+        → Current 5-candle activity is very quiet but multi-TF history shows
+           above-normal volume in longer frames. Quieting after a busy period.
+
+  indicators.vwap_zscore | MODULATES
+    volatility_clustering directly adjusts vwap_zscore thresholds internally.
+    See vwap_zscore.txt INDICATOR RELATIONSHIPS section.
+
+  indicators.regime | GATE
+    REVERSAL and ROLLOVER regimes require volatility_clustering >= 1.05.
+    This means these regimes CANNOT be active with low clustering.
+    IF regime = REVERSAL AND volatility_clustering < 1.05:
+      → Either regime data or clustering data is stale. Check timestamps.
+
+  indicators.squeeze indicators | CONTEXT
+    IF volatility_clustering < 0.85 during a squeeze (squeeze_energy > 5)
+      → The squeeze is building in a low-participation environment.
+        The release will be triggered when volume returns. Monitor for
+        volume_change_point probability rising.
+
+  indicators.volatility_clustering.change_point_probability | EMBEDDED
+    This sub-field detects volume REGIME SHIFTS. See volume_change_point.txt.
+    It is computed jointly with the main clustering value but is a different
+    type of analysis (Bayesian changepoint detection, not z-score).
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Read value (range [0.7, 1.5]); confirm range is not compared against 0-1 scale.
+  2  Determine volume regime: low (<0.9), normal (0.9-1.1), high (>1.1).
+  3  Note impact on other indicator reliability (see role section above).
+  4  Check change_point_probability sub-field for volume regime shifts.
+  5  Compare to activity_ratio for short vs long TF volume agreement.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF underlying TF volume data has gaps: volume z-scores will be skewed.
+  No explicit invalidation mechanism in the computation; check data source
+  freshness for any TF with anomalously zero volume.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF value is compared against 0-1 range thresholds
+    → RANGE ERROR. This indicator's range is [0.7, 1.5]. A value of 0.8
+       does NOT mean "80% of normal" in a 0-100 scale sense. It means
+       the weighted TF multiplier is at 0.8 (about 14% below the clamp floor
+       of 0.7, but only about 10% below neutral of 1.0). All threshold
+       comparisons must treat 1.0 as neutral.
+
+  IF volatility_clustering is confused with volatility itself
+    → DIFFERENT CONSTRUCT. volatility_clustering measures RELATIVE VOLUME
+       activity (via log z-scores), not price volatility. High clustering
+       means more volume than usual, not more price movement. Volatility_squeeze
+       is the price volatility indicator.

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

@@ -0,0 +1,169 @@
+================================================================================
+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.