@pgnio/helios-mcp 0.0.0-stage → 0.2.0

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

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

@@ -0,0 +1,128 @@
+================================================================================
+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/support_resistance.txt

@@ -0,0 +1,169 @@
+================================================================================
+INDICATOR: SUPPORT / RESISTANCE — DYNAMIC SUPPORT AND RESISTANCE LEVELS
+================================================================================
+id:                 support_resistance
+data_field:         indicators.support  (array of level objects)
+                    indicators.resistance  (array of level objects)
+type:               ARRAY of level objects
+update_rate:        per_tick
+latency_profile:    SLOW (multi-scale pivot clustering; KDE-based consolidation)
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+Support and resistance levels are detected via a hybrid system combining:
+  1. EMA(120) + ATR(14) bands — structural dynamic levels
+  2. Multi-scale pivot point clustering — historical price turning points
+  3. Bayesian Beta-Binomial strength scoring — statistical hold probability
+
+Each output is an array of level objects sorted by proximity to current price.
+
+Level object structure:
+  {
+    price:             price level (number)
+    distance:          % distance from current price (positive if above)
+    touches:           raw count of price interactions
+    weightedTouches:   volume and time-decay weighted touch count
+    strength:          STRONG | MODERATE | WEAK (based on weightedTouches)
+    source:            "ema_band" | "pivot_cluster" | "poc" | "polarity_flip"
+    bayesianStrength:  P(0..1) — Bayesian posterior probability the level holds
+  }
+
+PIVOT CLUSTERING (4 window scales: 240, 120, 60, 30 candles):
+  A pivot high exists when a candle has the highest High in its window.
+  A pivot low exists when a candle has the lowest Low in its window.
+  Pivots are KDE-smoothed (Gaussian kernel) and merged when within dead zone.
+
+WEIGHT FORMULA PER LEVEL:
+  timeWeight = f(age of level):
+    age <= 6h:   linear decay 1.0 → 0.8
+    6h - 24h:   linear decay 0.8 → 0.3
+    > 25h:      base weight 0.1
+  recencyBoost:   × 2.0 if age <= 240 minutes
+  volScore:       clamp(1 + (volume at level / avgVolume)^0.5, 1.0, 3.0)
+  weight = timeWeight × recencyBoost × volScore
+
+STRENGTH TIERS (by weightedTouches):
+  >= 3.0  →  STRONG
+  >= 1.5  →  MODERATE
+  >= 0.5  →  WEAK
+  < 0.5   →  filtered out (not emitted)
+
+DEAD ZONE FILTER:
+  min(ATR × 0.1, price × 0.001) — levels closer than this to each other
+  or to current price are filtered out (noise).
+
+BAYESIAN STRENGTH (Beta-Binomial over 2000-candle lookback):
+  At each level, over the last 2000 bars:
+    - Total times price approached the level: N
+    - Times price held/reversed at the level: k
+  bayesianStrength = (k + 1) / (N + 2)   [Laplace-smoothed Beta posterior]
+  Represents the empirical probability that the level holds when tested.
+
+POLARITY FLIPS:
+  A resistance level becomes support after 30 consecutive bars where price
+  holds >= 0.3% above the broken level. Vice versa for support → resistance.
+  source = "polarity_flip" for these converted levels.
+
+--------------------------------------------------------------------------------
+LEVEL INTERPRETATION
+--------------------------------------------------------------------------------
+  STRONG level (weightedTouches >= 3.0)
+    This level has been tested and respected multiple times with volume and time
+    weighting. Each time price has approached, it has reversed or consolidated.
+    High-significance structural level.
+
+  MODERATE level (weightedTouches 1.5-3.0)
+    Notable level with multiple weighted touches. Meaningful but not dominant.
+    Valid for stop reference and entry proximity but less reliable than STRONG.
+
+  WEAK level (weightedTouches 0.5-1.5)
+    Recent or lightly tested level. Provides short-term reference but may not
+    hold under strong directional pressure.
+
+  bayesianStrength thresholds:
+    >= 0.75  : high probability of holding at next test
+    0.50-0.74: moderate probability
+    < 0.50   : historically holds less than 50% of tests — treat as breakout zone
+
+ POLARITY FLIP levels:
+    Former resistance now support (or vice versa). These are often the most
+    significant structural levels — the price level has been validated as
+    a decision zone from both sides.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.poc | AMPLIFIES
+    A support level that coincides with POC (within dead zone tolerance)
+    has the highest structural significance in the entire system.
+    Two independent computations (volume profile + pivot clustering) agree.
+
+  indicators.vwap | AMPLIFIES
+    A support level near VWAP is doubly anchored (volume cost average +
+    price pivot). When these coincide during a pullback, they define the
+    highest-probability support zone.
+
+  indicators.value_area_high / value_area_low | CONTEXT
+    VA edges are implicit levels. When S/R indicator also identifies a level
+    near VA_High or VA_Low, the zone is confirmed by both methods.
+
+  indicators.hmi | CONTEXT
+    IF hmi >= 60 AND price pulls back to STRONG support
+      → Trend intact, prices testing known structural support. Standard
+         trend continuation zone.
+    IF hmi < 20 AND price is at STRONG resistance
+      → Low momentum meets high resistance. Structural ceiling may cap.
+
+  indicators.market_structure | COMPANION
+    market_structure = BREAKING_UP or CONFIRMED_BREAK_UP often coincides
+    with price breaking above a STRONG resistance level. Confirm the break
+    by checking which resistance level was breached.
+
+  indicators.activity_ratio | MODULATES
+    Levels formed during high activity_ratio periods have higher volScore
+    (capped at 3.0). Levels formed in dead-volume sessions are inherently weaker.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Read indicators.resistance array; nearest levels first.
+  2  Read indicators.support array; nearest levels first.
+  3  For each level: check strength and bayesianStrength.
+  4  Identify STRONG or polarity_flip levels near current price.
+  5  Cross-reference with poc and vwap proximity.
+  6  Gate interpretation with regime and hmi for directional context.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF activity_ratio < 0.5 AND the level was formed in the last 60 minutes
+    → Levels formed in dead-volume are low-quality. Bayesian strength will
+       be low; treat as WEAK regardless of touch count.
+
+  IF age of level > 25 hours AND timeWeight drops to 0.1
+    → Level is still in the array but has low effective weight. Verify
+       bayesianStrength is still >= 0.6 before treating as active.
+
+  IF market has gapped significantly (> 3% up or down) since level was formed
+    → Many historical levels below (upside gap) or above (downside gap) may
+       be in thin-trade zones. Bayesian strength may not reflect post-gap
+       behavior. Treat pre-gap levels with caution.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF all levels in the support array are treated equally
+    → INCOMPLETE. Use strength (STRONG/MODERATE/WEAK) and bayesianStrength
+       to differentiate. Only STRONG levels with bayesianStrength >= 0.65
+       should be used for stop placement or significant position decisions.
+
+  IF a resistance level is treated as a hard cap regardless of regime
+    → INCORRECT. In CASCADE/BREAKOUT regimes, resistance levels are
+       commonly broken. bayesianStrength < 0.5 at a resistance level means
+       it is statistically more likely to break than hold under pressure.
+
+  IF the support array is assumed to always be non-empty
+    → INCORRECT ASSUMPTION. Dead zones, filter thresholds, and low-touch
+       periods can result in empty or short arrays. Handle empty array case
+       explicitly.

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

@@ -0,0 +1,165 @@
+================================================================================
+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/trend_interpretation.txt

@@ -0,0 +1,98 @@
+================================================================================
+INDICATOR: TREND_INTERPRETATION
+================================================================================
+id:                 trend_interpretation
+data_field:         indicators.trend_interpretation
+type:               CATEGORICAL
+values:             STRONG | MODERATE | WEAK | RANGING_CHOPPY
+update_rate:        per_tick
+latency_profile:    COINCIDENT
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+trend_interpretation is a categorical label derived from indicators.trend_strength
+using fixed thresholds. It carries the same information as trend_strength in a
+discrete format. See trend_strength.txt for the full mathematical construction.
+
+Mapping:
+  trend_strength >= 60  →  STRONG
+  trend_strength >= 40  →  MODERATE
+  trend_strength >= 20  →  WEAK
+  trend_strength < 20   →  RANGING_CHOPPY
+
+This indicator has NO direction. STRONG does not mean STRONG UPWARD — it means
+the market is strongly moving in ONE direction. Use hmi or regime to determine
+which direction that is.
+
+--------------------------------------------------------------------------------
+STATE DEFINITIONS
+--------------------------------------------------------------------------------
+  STRONG
+    The directional imbalance across all weighted timeframe clusters is
+    significant (trend_strength >= 60). One direction dominates the
+    timeframe stack. Momentum strategies have a structural edge.
+
+  MODERATE
+    Notable directional imbalance exists (trend_strength 40-59) but is
+    not extreme. A trend is present and tradeable with reduced confidence.
+    Some countertrend TF activity is present.
+
+  WEAK
+    Faint directional bias only (trend_strength 20-39). Near-even balance
+    between up and down movement. Use directional indicators with caution.
+
+  RANGING_CHOPPY
+    Near-equal directional balance (trend_strength < 20). No meaningful
+    trend in any direction. Equivalent in implication to CHOP regime.
+    Discard momentum-based edge signals.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.trend_strength | SAME DATA
+    Always consistent. Use trend_interpretation for categorical branching
+    and trend_strength when numeric precision is needed (e.g., thresholds
+    within the MODERATE band).
+
+  indicators.regime | CROSS_VALIDATE
+    RANGING_CHOPPY state should co-occur with CHOP, CONSOL, or RANGING regime.
+    IF trend_interpretation = STRONG AND regime = CHOP
+      → Conflict. One is stale. Check timestamps and activity.
+    IF trend_interpretation = STRONG AND regime IN [CASCADE, BREAKOUT, TREND]
+      → Full agreement. Highest confidence trending condition.
+
+  indicators.hmi | CONTEXT
+    trend_interpretation indicates strength; hmi provides directional sign:
+    IF trend_interpretation = STRONG AND hmi > 40
+      → Strong directional trend to the upside.
+    IF trend_interpretation = STRONG AND hmi < -40
+      → Strong directional trend to the downside.
+    IF trend_interpretation = STRONG AND |hmi| < 20
+      → Trend strength diverges from hmi. Investigate which TF clusters
+         are driving trend_strength vs hmi to resolve.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Read state.
+  2  RANGING_CHOPPY: momentum-based inference is not supported.
+  3  Pair with hmi or regime for direction.
+  4  Most informative when state is MODERATE or STRONG.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  Same as trend_strength. If activity_ratio < 0.5: discard.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF STRONG state is interpreted as bullish
+    → INCORRECT. STRONG means one direction dominates — direction
+       unknown from this field alone. Pair with hmi direction.
+
+  IF WEAK is treated as "no edge"
+    → PARTIALLY CORRECT. Weak trend means reduced directional edge from
+       trend-following, but mean-reversion setups may still be valid.
+       Check vwap_zscore and S/R distance in WEAK states.