@pgnio/helios-mcp 0.0.0-stage → 0.2.0

package/dist/index.mjs

@@ -0,0 +1,52 @@
+import {
+  FileAgentSessionStore,
+  HOSTED_RECONNECT_MESSAGE,
+  HeliosAgentMcpAccountService,
+  HeliosAgentMcpAuthService,
+  HeliosAgentMcpDocsService,
+  HeliosAgentMcpLedgerService,
+  HeliosAgentMcpMarketService,
+  HeliosAgentMcpProviderService,
+  HeliosAgentMcpTradingService,
+  MemoryAgentMcpSessionStore,
+  createHeliosAccountToolDefinitions,
+  createHeliosAgentMcpServer,
+  createHeliosAuthToolDefinitions,
+  createHeliosDocsToolDefinitions,
+  createHeliosLedgerToolDefinitions,
+  createHeliosMarketToolDefinitions,
+  createHeliosProviderToolDefinitions,
+  createHeliosTradingToolDefinitions,
+  formatHeliosLoginPrompt,
+  getDefaultHeliosAgentMcpDocsRoot,
+  getDefaultHeliosAgentMcpSessionPath,
+  pendingAgentLoginSchema,
+  retryAfterUnauthorizedRefresh,
+  toolAnnotations
+} from "./chunk-NWGWXYTS.mjs";
+export {
+  FileAgentSessionStore,
+  HOSTED_RECONNECT_MESSAGE,
+  HeliosAgentMcpAccountService,
+  HeliosAgentMcpAuthService,
+  HeliosAgentMcpDocsService,
+  HeliosAgentMcpLedgerService,
+  HeliosAgentMcpMarketService,
+  HeliosAgentMcpProviderService,
+  HeliosAgentMcpTradingService,
+  MemoryAgentMcpSessionStore,
+  createHeliosAccountToolDefinitions,
+  createHeliosAgentMcpServer,
+  createHeliosAuthToolDefinitions,
+  createHeliosDocsToolDefinitions,
+  createHeliosLedgerToolDefinitions,
+  createHeliosMarketToolDefinitions,
+  createHeliosProviderToolDefinitions,
+  createHeliosTradingToolDefinitions,
+  formatHeliosLoginPrompt,
+  getDefaultHeliosAgentMcpDocsRoot,
+  getDefaultHeliosAgentMcpSessionPath,
+  pendingAgentLoginSchema,
+  retryAfterUnauthorizedRefresh,
+  toolAnnotations
+};

package/docs/ai-agent-indicators/00_index.txt

@@ -0,0 +1,210 @@
+================================================================================
+HELIOS INDICATOR INDEX — AI AGENT REFERENCE
+================================================================================
+# One entry per indicator. Format: file | data_field | type | range | purpose
+# All fields accessed via: indicators.<data_field>
+
+--------------------------------------------------------------------------------
+MOMENTUM / DIRECTION
+--------------------------------------------------------------------------------
+hmi.txt
+  indicators.hmi | NUMERIC | -100..100
+  Weighted cross-timeframe momentum composite (12 TFs, Kalman/Bayesian).
+  REQUIRED_COMPANION: hmi_velocity. INVALIDATED BY: activity_ratio < 0.5, regime = CHOP/CONSOL.
+
+hmi_velocity.txt
+  indicators.hmi_velocity | NUMERIC | unbounded (practical: -15..+15)
+  EMA of HMI delta (alpha=0.15). Resolves direction at ambiguous HMI levels (15..40).
+  REQUIRED_COMPANION: hmi. Meaningless if hmi IN -15..15.
+
+regime.txt
+  indicators.regime | CATEGORICAL
+  19-state market regime classifier (e.g. CASCADE_UP, CHOP, REVERSAL).
+  PRIMARY GATE: invalidates all momentum indicators when CHOP/CONSOL/RANGING.
+
+tf_alignment.txt
+  indicators.tf_alignment | NUMERIC | 0..100
+  % of short-TF (1m-2h) movement aligned with macro (4h-24h) direction.
+  Breadth complement to HMI magnitude.
+
+directional_efficiency.txt
+  indicators.directional_efficiency | NUMERIC | -1..1
+  Kaufman efficiency ratio: net directional movement / total movement across all TFs.
+  Measures cleanliness not direction. Cluster sub-fields available.
+
+hurst_exponent.txt
+  indicators.hurst_exponent | NUMERIC | 0..1
+  R/S analysis on 1m returns. > 0.6 = trending persistence. < 0.4 = mean-reverting.
+  Exactly 0.5 = insufficient data (< 16 returns). Slow/lagging.
+
+--------------------------------------------------------------------------------
+TREND STRENGTH
+--------------------------------------------------------------------------------
+trend_strength.txt
+  indicators.trend_strength | NUMERIC | 0..100
+  DX-style directional index. Directional imbalance across weighted TF clusters.
+  Direction-agnostic — pair with hmi or regime for direction.
+
+trend_interpretation.txt
+  indicators.trend_interpretation | CATEGORICAL | STRONG / MODERATE / WEAK / RANGING_CHOPPY
+  Categorical alias of trend_strength (same computation, fixed thresholds).
+  Use for state-based branching; use trend_strength for numeric precision.
+
+--------------------------------------------------------------------------------
+OSCILLATORS / RSI
+--------------------------------------------------------------------------------
+weighted_rsi.txt
+  indicators.weighted_rsi | NUMERIC | 0..100
+  Multi-TF EWMA RSI blended across 12 TFs (1m-dominant, alpha=0.3).
+  REQUIRED_COMPANION: bayesian_overbought. Invalidated if activity_ratio < 0.5.
+
+bayesian_overbought.txt
+  indicators.bayesian_overbought | NUMERIC | 0..1
+  Beta-Binomial posterior: P(current RSI >= historical 60-obs window).
+  Contextualizes weighted_rsi in historical percentile terms.
+
+rsi_divergence.txt
+  indicators.rsi_divergence | CATEGORICAL | BULLISH_DIVERGENCE / BEARISH_DIVERGENCE / NONE
+  Slope divergence between price and weighted_rsi over 20-bar window.
+  Valid only at RSI extremes: BULLISH when RSI <= 35; BEARISH when RSI >= 65.
+
+--------------------------------------------------------------------------------
+MACD
+--------------------------------------------------------------------------------
+macd_histogram.txt
+  indicators.macd_histogram | NUMERIC | unbounded (normalize by price)
+  Standard MACD(12,26,9) histogram, normalized by close price.
+  Growing/shrinking vs zero direction is more informative than absolute level.
+
+macd_signal.txt
+  indicators.macd_signal | CATEGORICAL | BULLISH_CROSS / BEARISH_CROSS / BULLISH / BEARISH / NEUTRAL
+  State-encoded MACD direction from same computation as histogram.
+  CHOP gate: all states unreliable in CHOP regime.
+
+macd_divergence.txt
+  indicators.macd_divergence | CATEGORICAL | BULLISH / BEARISH / "" (empty = none)
+  Peak/trough swing divergence: price vs MACD histogram peaks over rolling window.
+  Peak-based; requires 2 completed swings. Independent of rsi_divergence.
+
+--------------------------------------------------------------------------------
+VOLUME PROFILE
+--------------------------------------------------------------------------------
+vwap.txt
+  indicators.vwap | PRICE LEVEL
+  7-day rolling VWAP (cumulative TPV / volume). NOT session VWAP.
+  REQUIRED_COMPANION: vwap_zscore. Bands at ±1σ and ±2σ also available.
+
+vwap_zscore.txt
+  indicators.vwap_zscore | NUMERIC | unbounded (typical: -4..+4)
+  z-score of (price - vwap) / volumeWeightedStdDev. Modulated by volatility_clustering.
+  FAR_ABOVE (> 2.0) meaning changes under different volatility_clustering conditions.
+
+poc.txt
+  indicators.poc | PRICE LEVEL
+  Highest-volume price level from 50-bucket volume profile over rolling history.
+  REQUIRED_COMPANION: poc_distance. VA boundaries also emitted.
+
+poc_distance.txt
+  indicators.poc_distance | NUMERIC | unbounded (typical: -10..+10, %)
+  % distance from current price to POC. Positive = above. Negative = below.
+  Mean-reversion thesis only when regime is non-trending.
+
+value_area_position.txt
+  indicators.value_area_position | CATEGORICAL | ABOVE VA / IN VA / BELOW VA
+  Price position relative to 70% volume zone (VA). Requires regime for interpretation.
+  ABOVE VA = mean-reversion in CHOP; continuation in CASCADE/BREAKOUT.
+
+support_resistance.txt
+  indicators.support | ARRAY of level objects
+  indicators.resistance | ARRAY of level objects
+  Hybrid EMA+ATR + pivot clustering + KDE, Bayesian Beta-Binomial hold probability.
+  Fields: price, distance%, touches, weightedTouches, strength (STRONG/MODERATE/WEAK),
+          source, bayesianStrength. Never assume array is non-empty.
+
+--------------------------------------------------------------------------------
+DERIVATIVES FLOW
+--------------------------------------------------------------------------------
+hfi.txt
+  indicators.hfi | NUMERIC | -100..100
+  Helios Flow Index: Bayesian composite of funding rate, OI delta, CVD slope.
+  REQUIRED_COMPANION: hfi_weights. Measures derivatives sentiment, not price direction.
+
+hfi_weights.txt
+  indicators.hfi_weights | OBJECT | { funding, oi, cvd } each [0..1], sum=1
+  Real-time Bayesian component weights for HFI computation.
+  Any weight < 0.10 = that data source is degraded.
+
+--------------------------------------------------------------------------------
+VOLATILITY / SQUEEZE
+--------------------------------------------------------------------------------
+volatility_squeeze.txt
+  indicators.volatility_squeeze | NUMERIC | [0, ∞); typical [0.1, 1.5]
+  Short/long GARCH(1,1) ratio. LOWER = MORE compressed (< 0.8 = in squeeze).
+  Counterintuitive scale: value 0.2 = maximum squeeze, NOT minimum.
+
+squeeze_duration.txt
+  indicators.squeeze_duration | INTEGER | [0, ∞)
+  Count of consecutive ticks with volatility_squeeze < 0.8. Resets to 0 on break.
+
+squeeze_energy.txt
+  indicators.squeeze_energy | NUMERIC | [0, ∞)
+  Integrated compression: squeeze_duration × (0.8 - volatility_squeeze).
+  Summary measure of pent-up energy. Zero = no active squeeze.
+
+volatility_clustering.txt
+  indicators.volatility_clustering | NUMERIC | [0.7, 1.5]  ← NOT [0, 1]
+  Weighted average of 6-TF log-volume z-scores as a confidence multiplier.
+  1.0 = neutral baseline. < 0.9 = below-norm. > 1.1 = above-norm.
+  Adjusts vwap_zscore thresholds internally.
+
+volume_change_point.txt
+  indicators.volatility_clustering.change_point_probability | NUMERIC | [0, 1]
+  Embedded sub-field of volatility_clustering (BOCPD algorithm).
+  P(volume regime just shifted this tick). > 0.5 is notable; > 0.7 is strong.
+
+--------------------------------------------------------------------------------
+MARKET STRUCTURE
+--------------------------------------------------------------------------------
+market_structure.txt
+  indicators.market_structure | CATEGORICAL
+  Values: RANGING / CONSOL / BREAKING_UP / BREAKING_DOWN /
+          CONFIRMED_BREAK_UP / CONFIRMED_BREAK_DOWN / TEST_RS / FAILED_BREAK
+  9-state HMM + ATR. CONFIRMED requires 3 consecutive ticks above/below S/R.
+  SUB-FIELD: indicators.market_structure.transitionConfidence [0..1] — HMM posterior.
+
+--------------------------------------------------------------------------------
+VOLUME / ACTIVITY
+--------------------------------------------------------------------------------
+activity_ratio.txt
+  indicators.activity_ratio | NUMERIC | [0, ∞); 1.0 = baseline
+  Recent 5-candle volume vs time-of-day normalized 1-day baseline.
+  PRIMARY INVALIDATION GATE for all other indicators at ratio < 0.5.
+  SUB-FIELD: indicators.activity_ratio.active [BOOLEAN] = true if ratio >= 0.5.
+  REVERSAL and ROLLOVER regimes require ratio >= 1.0.
+
+activity_zscore.txt
+  indicators.activity_zscore | NUMERIC | log-normal; typical -3..+4
+  Log-normal z-score of current tick volume vs same-hour 1-day baseline.
+  Single-tick detector (not 5-candle window). Companion to activity_ratio.
+
+================================================================================
+DEPENDENCY MAP — KEY RELATIONSHIPS
+================================================================================
+# Read bottom-up: left depends on right being valid first.
+
+  ALL INDICATORS        →  activity_ratio (< 0.5 invalidates most momentum signals)
+  hmi                   →  hmi_velocity (required for hmi IN -30..30)
+  hmi_velocity          →  hmi (parent; has no meaning without it)
+  weighted_rsi          →  bayesian_overbought (raw RSI needs percentile context)
+  rsi_divergence        →  weighted_rsi (extremes gate: valid only at RSI <= 35 / >= 65)
+  macd_signal           →  macd_histogram (state without magnitude is incomplete)
+  macd_divergence       →  macd_signal (divergence leads; cross confirms)
+  hfi                   →  hfi_weights (composite without component split is opaque)
+  squeeze_energy        →  volatility_squeeze + squeeze_duration (derived from both)
+  vwap_zscore           →  vwap + volatility_clustering (both required for interpretation)
+  poc_distance          →  poc (normalized deviation requires knowing the level)
+  value_area_position   →  regime (same state is opposite signal in different regimes)
+  volatility_clustering →  (modulates vwap_zscore internally at computation time)
+  volume_change_point   →  volatility_clustering (embedded sub-field, not standalone)
+  market_structure      →  support/resistance (uses S/R levels for BREAKING/TEST states)
+  regime                →  (no upstream dependency; invalidates downstream indicators)

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

@@ -0,0 +1,166 @@
+================================================================================
+INDICATOR: ACTIVITY_RATIO — VOLUME ACTIVITY RATIO
+================================================================================
+id:                 activity_ratio
+data_field:         indicators.activity_ratio
+type:               NUMERIC
+range:              [0, ∞); 1.0 = exactly at baseline
+precision:          3 decimal places
+update_rate:        per_tick
+latency_profile:    COINCIDENT
+
+ADDITIONAL FIELD:
+  indicators.activity_ratio.active
+  type:   BOOLEAN
+  value:  true if activity_ratio >= 0.5, false if < 0.5
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+activity_ratio compares the recent 5-candle volume average against a time-of-day
+normalized 1-day baseline, producing a ratio that reflects how active the market
+is currently vs its typical activity at this time of day.
+
+Recent window:
+  recent = average volume of the last 5 candles (1m each = 5 minutes)
+
+Baseline construction:
+  1. Collect all candles from the last 1 day (~1440 1m candles).
+  2. IF the time-of-day group (matching UTC hour) has >= 10 candles available:
+       baseline = average volume of candles in the SAME UTC HOUR over the past day.
+       (Time-of-day normalized — compares against same-hour behavior.)
+  3. ELSE:
+       baseline = average volume of ALL candles in the past 1 day.
+       (Falls back to all-day average if insufficient same-hour history.)
+
+  ratio = recent / baseline
+
+Time-of-day normalization is important because:
+  - Asian session typically has lower volume than US session
+  - Comparing current volume against the same-hour baseline prevents
+    falsely labeling Asian session volume as "dead" just because it's
+    lower than a full-day average
+
+--------------------------------------------------------------------------------
+RANGE INTERPRETATION
+--------------------------------------------------------------------------------
+  value >= 1.5
+    Volume is significantly above the typical rate for this time of day.
+    Very active market. High participation. Data quality for all indicators
+    is at its best. Price moves in this state are better sustained and
+    represent genuine market conviction.
+
+  value >= 1.0 AND value < 1.5
+    Volume at or above baseline. Active conditions. Price action is supported
+    by at least typical participation. Directional signals are reliable.
+    REVERSAL and ROLLOVER regimes require value >= 1.0.
+
+  value >= 0.5 AND value < 1.0
+    Below-baseline but not dead. Volume is 50%-100% of the typical rate.
+    activity_ratio.active = true.
+    Directional signals should be used with moderate caution. Some signals
+    will be lower quality but not completely unreliable.
+
+  value < 0.5
+    Very low volume. Dead market conditions.
+    activity_ratio.active = false.
+    ALL directional indicators should be treated with significant skepticism.
+    This threshold is the primary invalidation gate for many indicators.
+
+--------------------------------------------------------------------------------
+ACTIVITY STATES — OPERATIONAL LABELS
+--------------------------------------------------------------------------------
+  ACTIVE:  value >= 1.0
+    Most indicator readings reliable. Regime classifications including
+    REVERSAL and ROLLOVER are eligible. HFI CVD component is reliable.
+    Breakout signals should be considered.
+
+  MODERATE: value >= 0.5 AND value < 1.0
+    Most momentum indicators still valid but with reduced confidence.
+    Support/resistance levels have lower hold probability in moderate volume.
+    REVERSAL/ROLLOVER regimes are gated out (require ACTIVE).
+
+  DEAD: value < 0.5
+    invalidate indicators: weighted_rsi, hfi (especially CVD component),
+    directional_efficiency, trend_strength. These are all computed from
+    price/volume data that has no meaningful signal with dead volume.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS — ROLE AS INVALIDATION GATE
+--------------------------------------------------------------------------------
+# activity_ratio is the primary PREREQUISITE GATE for all other indicators.
+# If value < 0.5, the following should be explicitly discarded:
+
+  indicators.weighted_rsi        → DISCARD if activity_ratio < 0.5
+  indicators.directional_efficiency → DISCARD if activity_ratio < 0.5
+  indicators.trend_strength      → DISCARD if activity_ratio < 0.5
+  indicators.hfi (CVD component) → SIGNIFICANTLY REDUCED if activity_ratio < 0.5
+  indicators.macd_histogram      → REDUCED (slow EMA less reliable)
+  indicators.support (new levels) → DISCARD levels formed in this period
+
+# Regime-specific gates:
+  indicators.regime = REVERSAL   → REQUIRES activity_ratio >= 1.0
+  indicators.regime = ROLLOVER   → REQUIRES activity_ratio >= 1.0
+
+  indicators.hmi | CONTEXT
+    HMI is somewhat more resistant to low volume (uses historical TF data)
+    but readings should still be downweighted when activity_ratio < 0.5.
+
+  indicators.volatility_squeeze | COMPANION
+    IF activity_ratio < 0.5 AND volatility_squeeze < 0.5
+      → Both volume AND price volatility are compressed. Maximum dual-quiet
+         state. All directional indicators degraded. Wait for volume return.
+
+  indicators.volatility_clustering | COMPANION
+    activity_ratio measures recent 5-candle activity for current-moment gating.
+    volatility_clustering measures multi-TF volume z-scores for longer context.
+    They typically agree on direction but activity_ratio reacts faster to sudden
+    volume changes; clustering reacts more smoothly.
+
+  indicators.activity_zscore | COMPANION
+    activity_ratio: current/baseline ratio (multiplicative measure).
+    activity_zscore: z-score on log volume (standardized statistical measure).
+    Both represent volume activity but from different statistical perspectives.
+    Together they provide a fuller view of volume state.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Read activity_ratio value AND activity_ratio.active boolean.
+  2  Determine state: ACTIVE (>= 1.0), MODERATE (0.5-1.0), or DEAD (< 0.5).
+  3  DEAD state: weighted_rsi, directional_efficiency, trend_strength, HFI CVD are invalid.
+  4  MODERATE state: reduced confidence on all signals.
+  5  Gate REVERSAL/ROLLOVER regime states (require ACTIVE).
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  activity_ratio is itself a near-primary indicator — it does not depend on
+  other signals for validity.
+
+  IF baseline (1-day history) is not yet available (market just listed)
+    → Falls back to all-day average. If even that is < 10 candles, baseline
+       may be unreliable. Treat activity_ratio = 1.0 as default on fresh starts.
+
+  IF volume data has gaps (candles with zero volume)
+    → average over 5-candle window may include zero-volume candles.
+       result will be suppressed artificially. Verify data source integrity.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF activity_ratio is only consulted for specific indicators and not others
+    → INCOMPLETE APPLICATION. activity_ratio < 0.5 is a system-wide gate.
+       It is not sufficient to gate only RSI while continuing to act on
+       regime or MACD signals. Apply the invalidation to ALL indicators.
+
+  IF activity_ratio = 1.0 is interpreted as "maximum activity"
+    → INCORRECT. 1.0 is exactly the baseline (neutral, normal activity).
+       Values up to 3.0+ are possible during squeezes or major events.
+       1.0 is normal, not exceptional.
+
+  IF time-of-day normalization is ignored when comparing across sessions
+    → CONTEXT ERROR. activity_ratio compares against the same UTC hour baseline.
+       A ratio of 0.8 during a typically quiet Asian session is different
+       from 0.8 during peak US session. Do not compare activity_ratio values
+       across different UTC hours as if they represent the same absolute volume.

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

@@ -0,0 +1,166 @@
+================================================================================
+INDICATOR: ACTIVITY_ZSCORE — VOLUME ACTIVITY Z-SCORE
+================================================================================
+id:                 activity_zscore
+data_field:         indicators.activity_zscore
+type:               NUMERIC
+range:              Unbounded; follows log-normal distribution; practical range -3 to +4
+precision:          3 decimal places
+update_rate:        per_tick
+latency_profile:    COINCIDENT
+
+--------------------------------------------------------------------------------
+CONSTRUCT
+--------------------------------------------------------------------------------
+activity_zscore is a standardized measure of current volume expressed as a
+log-normal z-score against the same 1-day time-of-day normalized baseline
+used by activity_ratio. It provides a statistically rigorous alternative view
+of volume deviation.
+
+Computation:
+  Uses the same baseline as activity_ratio (see activity_ratio.txt):
+  - 1-day lookback, time-of-day normalized (current UTC hour if >= 10 candles)
+
+  logVols   = log(volume) for each candle in baseline window
+  mean_log  = mean(logVols)
+  std_log   = standard deviation(logVols)
+
+  currentLogVol = log(currentVol) (most recent 1m candle volume)
+  
+  activity_zscore = (currentLogVol - mean_log) / std_log
+
+Using log-normal distribution is appropriate because trading volume:
+  - Is always positive (log transform required)
+  - Has right-skewed distribution at linear scale
+  - Becomes approximately normal at log scale
+
+This z-score is more statistically robust than activity_ratio for detecting
+truly unusual volume events, because:
+  - It accounts for the distribution shape (not just mean ratio)
+  - It handles asymmetry correctly (equal-magnitude upside and downside spikes)
+
+--------------------------------------------------------------------------------
+RANGE INTERPRETATION
+--------------------------------------------------------------------------------
+  value > 3.0
+    Extreme volume spike. Current volume is at the top 0.1% of the historical
+    1-day log-normal distribution for this time of day. This represents a
+    major volume event: large liquidation, significant news, institutional
+    block, or market shock. Very rare in untriggered conditions.
+
+  value > 2.0 AND value <= 3.0
+    Strong volume spike. Current tick volume is unusually high relative to
+    the 1-day same-hour baseline. Top ~2.5% of observations. Associated with
+    breakout initiations, forced liquidations, or high-activity news reactions.
+
+  value > 1.0 AND value <= 2.0
+    Above average. Current volume is elevated but not extreme. Top ~16%
+    of observations. Increases confidence in directional signals at the
+    current tick. Suggests active participation without being a shock event.
+
+  value >= -1.0 AND value <= 1.0
+    Normal range. Within ±1 standard deviation of the mean log-volume for
+    this time of day. Average conditions; baseline reliability for all indicators.
+
+  value >= -2.0 AND value < -1.0
+    Below average. Current tick volume is lighter than typical.
+    Directional signals carry some reduction in reliability.
+
+  value < -2.0
+    Unusually quiet. Current tick volume is at the bottom ~2.5% of
+    historical observations for this time of day. Very low participation.
+    Most indicator signals should be treated with increased skepticism.
+
+  value < -3.0
+    Extremely quiet tick. Extremely unusual absence of volume.
+    Potential data gap or trading halt. Treat as similar to activity_ratio < 0.5.
+
+--------------------------------------------------------------------------------
+COMPARISON WITH ACTIVITY_RATIO
+--------------------------------------------------------------------------------
+# Both indicators measure volume activity vs baseline. They are complementary.
+
+  activity_ratio approaches volume as: recent_average / baseline_average
+    - Intuitively: "current MA of volume is X times the baseline MA"
+    - Good for: sustained elevated/depressed volume conditions
+    - Limitation: sensitive to outliers if recent candles contain spikes
+
+  activity_zscore approaches volume as: log-normal z-score of current candle
+    - Intuitively: "this tick's volume is X standard deviations from normal"
+    - Good for: detecting sudden single-tick volume spikes/crashes
+    - Limitation: single-tick; may miss sustained moderate elevation
+
+  Use activity_ratio as the primary gate (covers 5-candle window).
+  Use activity_zscore to detect instantaneous unusual events (single tick).
+
+  Agreement examples:
+    activity_ratio >= 1.0 AND activity_zscore > 1.0
+      → Sustained and current high volume. Full confidence conditions.
+
+    activity_ratio < 0.5 AND activity_zscore < -2.0
+      → Both agree on extreme quiet. Double confirmation of dead market.
+
+  Divergence examples:
+    activity_ratio = 0.4 (quiet recent window) AND activity_zscore = 2.5 (this tick spike)
+      → The current tick has spiked despite a quiet recent period.
+         A sudden large order or news event on a quiet tape. High significance.
+
+    activity_ratio = 1.5 (elevated recent window) AND activity_zscore = -0.5 (this tick quiet)
+      → Current tick is quiet but the recent window has been active.
+         The immediate activity is normalizing after a busy period.
+
+--------------------------------------------------------------------------------
+INDICATOR RELATIONSHIPS
+--------------------------------------------------------------------------------
+  indicators.activity_ratio | COMPANION
+    Use together as described above. activity_ratio for window-level gate;
+    activity_zscore for tick-level event detection.
+
+  indicators.volume_change_point | COMPANION
+    change_point_probability detects volume REGIME shifts (sustained changes).
+    activity_zscore detects tick-level spikes (momentary changes).
+    IF both are elevated simultaneously:
+      → A sudden volume spike that also exceeds BOCPD detection threshold.
+         Rare and high-significance volume event.
+
+  indicators.hfi | CONTEXT
+    activity_zscore > 2.0 at the same tick as HFI CVD component change
+    suggests a large real-money order flow event at that specific moment.
+
+  indicators.squeeze indicators | ALERT
+    IF squeeze_energy > 10 AND activity_zscore > 2.0 fires
+      → Volume spike into a compressed market. Classic squeeze release trigger.
+         Monitor next few ticks for the directional breakout to confirm.
+
+--------------------------------------------------------------------------------
+DEPENDENCY ORDER
+--------------------------------------------------------------------------------
+  1  Check activity_ratio first (5-candle window gate).
+  2  Read activity_zscore for current-tick event context.
+  3  Identify divergences between activity_ratio and activity_zscore.
+  4  If zscore > 2.0 during low activity_ratio: potential sudden volume event.
+  5  Combine with squeeze_energy and volume_change_point for breakout context.
+
+--------------------------------------------------------------------------------
+INVALIDATION CONDITIONS
+--------------------------------------------------------------------------------
+  IF std_log ≈ 0 (near-constant volume in 1-day baseline)
+    → Division by near-zero. z-score is unstable. Extremely unlikely in
+       practice except during exchange testing periods or extended maintenance.
+
+  IF baseline window has fewer than 10 candles
+    → std_log estimate is unreliable. Treat as approximately 0.
+
+--------------------------------------------------------------------------------
+ANTI-PATTERNS — DETECTABLE MISUSE CONDITIONS
+--------------------------------------------------------------------------------
+  IF activity_zscore > 2.0 is used as a standalone trade trigger
+    → INCORRECT. High z-score means unusual volume at THIS TICK. Volume
+       can spike without directional follow-through. Requires directional
+       confirmation from hmi, regime, or market_structure.
+
+  IF activity_zscore is used instead of activity_ratio as the primary gate
+    → WRONG GATE. activity_ratio covers the 5-candle window for sustained volume
+       gating; activity_zscore is a single-tick measure. Using only
+       activity_zscore for gating may pass indicators during a dead
+       market that just had one unusual tick. Use activity_ratio as the gate.