@pgnio/helios-mcp 0.2.6 → 0.2.8

package/dist/cli.js

@@ -2618,7 +2618,7 @@ function createHeliosMarketToolDefinitions(service) {
     {
       name: "helios_market_get_snapshot",
       title: "Get Helios Market Snapshot",
-      description: "Returns a compact market snapshot for the selected, all, or explicitly requested symbols. By default: the top 50 coins by market cap with the main columns; name symbols to get other coins, pass fields for other columns.",
+      description: "Returns a compact market snapshot for the selected, all, or explicitly requested symbols. By default: the top 50 coins by market cap with the main columns; name symbols to get other coins, pass fields for other columns. What each column means: helios_docs_get_document with path ai-agent-indicators/00_columns.txt (read it once).",
       inputSchema: marketSnapshotInputSchema,
       async execute(input) {
         const result = marketSnapshotToolOutputSchema.parse(await service.getSnapshot(input));
@@ -2886,7 +2886,7 @@ async function createHeliosAgentMcpServer(options) {
   const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
   const server = new McpServer({
     name: "helios",
-    version: "0.2.6"
+    version: "0.2.8"
   });
   const sessionStore = options.sessionStore ?? new FileAgentSessionStore(options.sessionPath ?? getDefaultHeliosAgentMcpSessionPath());
   const client = new HeliosAgentAuthClient({
@@ -2982,7 +2982,10 @@ function toolAnnotations(name) {
 var TEXT_IS_RESULT = /* @__PURE__ */ new Set(["helios_docs_get_document"]);
 function withDataText(name, content, structuredContent) {
   if (TEXT_IS_RESULT.has(name)) return content;
-  return [...content, { type: "text", text: JSON.stringify(structuredContent) }];
+  const summary = content.map((block) => block.text).join("\n\n");
+  return [{ type: "text", text: `${summary}
+
+${JSON.stringify(structuredContent)}` }];
 }
 function registerTool(server, tool) {
   server.registerTool(

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   createHeliosAgentMcpServer
-} from "./chunk-WLCFIWFP.mjs";
+} from "./chunk-UHFLF3UG.mjs";
 
 // src/cli.ts
 async function main() {

package/dist/index.js

@@ -2692,7 +2692,7 @@ function createHeliosMarketToolDefinitions(service) {
     {
       name: "helios_market_get_snapshot",
       title: "Get Helios Market Snapshot",
-      description: "Returns a compact market snapshot for the selected, all, or explicitly requested symbols. By default: the top 50 coins by market cap with the main columns; name symbols to get other coins, pass fields for other columns.",
+      description: "Returns a compact market snapshot for the selected, all, or explicitly requested symbols. By default: the top 50 coins by market cap with the main columns; name symbols to get other coins, pass fields for other columns. What each column means: helios_docs_get_document with path ai-agent-indicators/00_columns.txt (read it once).",
       inputSchema: marketSnapshotInputSchema,
       async execute(input) {
         const result = marketSnapshotToolOutputSchema.parse(await service.getSnapshot(input));
@@ -2960,7 +2960,7 @@ async function createHeliosAgentMcpServer(options) {
   const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
   const server = new McpServer({
     name: "helios",
-    version: "0.2.6"
+    version: "0.2.8"
   });
   const sessionStore = options.sessionStore ?? new FileAgentSessionStore(options.sessionPath ?? getDefaultHeliosAgentMcpSessionPath());
   const client = new HeliosAgentAuthClient({
@@ -3056,7 +3056,10 @@ function toolAnnotations(name) {
 var TEXT_IS_RESULT = /* @__PURE__ */ new Set(["helios_docs_get_document"]);
 function withDataText(name, content, structuredContent) {
   if (TEXT_IS_RESULT.has(name)) return content;
-  return [...content, { type: "text", text: JSON.stringify(structuredContent) }];
+  const summary = content.map((block) => block.text).join("\n\n");
+  return [{ type: "text", text: `${summary}
+
+${JSON.stringify(structuredContent)}` }];
 }
 function registerTool(server, tool) {
   server.registerTool(

package/dist/index.mjs

@@ -29,7 +29,7 @@ import {
   topOfSnapshot,
   withDataText,
   withSnapshotDefaults
-} from "./chunk-WLCFIWFP.mjs";
+} from "./chunk-UHFLF3UG.mjs";
 export {
   DEFAULT_SNAPSHOT_FIELDS,
   DEFAULT_SNAPSHOT_TOP,

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

@@ -0,0 +1,74 @@
+HELIOS SNAPSHOT COLUMNS: HOW TO READ THEM
+Short guide to the column ids in helios_market_get_snapshot, _chunk and symbol detail `row`.
+All % values are already percent (2.5 = 2.5%). null = unavailable, never zero.
+Longer guides for single indicators are in this folder (see 00_index.txt).
+
+PRICE AND SIZE
+rank   market cap rank (1 = largest). null = unranked.
+lp     last price.
+qv     24h quote volume in USD. Low qv = thin market, wider fills.
+bv     24h base volume (coins).
+
+RETURNS (% change over the window)
+r1m r3m r5m r15m r30m r1h r2h r4h r6h r8h r12h r24h r3d r7d
+
+DISTANCE FROM RECENT RANGE
+fh24 fh7   % from the 24h / 7d high. Always <= 0. -10 = 10% below the high.
+fl24 fl7   % from the 24h / 7d low. Always >= 0. 2 = 2% above the low.
+           Near 0 on fl = sitting on the low; near 0 on fh = at the high.
+
+REGIME AND MOMENTUM
+reg    regime label from 12 timeframe changes:
+       up:      CASCADE UP, PARABOLIC, BREAKOUT, TREND UP, GRIND UP, SPIKE UP
+       down:    CASCADE DOWN, CRASH, BREAKDOWN, TREND DN, BLEED, SPIKE DN
+       turning: REVERSAL (down->up), ROLLOVER (up->down), EXHAUST UP, EXHAUST DN
+       no trend: CHOP, CONSOL, RANGING (momentum signals are weak here)
+       Known quirk: a steady fall can read CRASH even when not accelerating.
+hmi    Helios momentum index, -100..100. Cross-timeframe momentum, 1h-4h weigh most.
+       > 40 strong up, 15..40 up, -15..15 no direction, < -40 strong down.
+hmiv   hmi velocity (rate of change of hmi). > 0 momentum improving, < 0 fading.
+       Meaningless when hmi is between -15 and 15.
+tri    trend strength label: STRONG TREND, MODERATE TREND, WEAK TREND, RANGING/CHOPPY.
+       No direction: use hmi or reg for which way.
+trv    trend strength 0..100 (> 60 STRONG, > 40 MODERATE, > 20 WEAK).
+de     directional efficiency -1..1. +1 every timeframe moving up cleanly,
+       -1 every timeframe moving down cleanly, near 0 choppy.
+
+STRETCH
+ob     overbought, 0..100 (weighted RSI across timeframes). >= 70 stretched up,
+       <= 30 stretched down.
+obosp  probability ob is high versus its own last 60 readings, 0..1.
+       > 0.9 extreme for this coin right now, < 0.1 extreme low.
+       In a strong trend ob can be 95 while obosp is low; read both.
+vwz    VWAP z-score vs the 7d VWAP. > +2 far above, -0.5..0.5 at VWAP, < -2 far below.
+
+STRUCTURE
+ms     market structure: RANGING, CONSOL (compressed), BREAKING↑ / BREAKING↓,
+       CONFIRMED-BREAK↑ / ↓, TEST-S (testing support), TEST-R (testing resistance),
+       FAILED-BREAK (breakout that reversed).
+srs    nearest support price. srr nearest resistance price (null = none found).
+
+SCORE
+hs     Helios score, a mean-reversion setup score. Positive = long setup
+       (needs ob <= 30 and de <= -0.4), negative = short setup (ob >= 60, de >= 0.4),
+       0 = no setup. Size: 5+ notable, 7+ strong, 9+ rare. Short scores have not
+       held up in backtests; long scores in a falling market have.
+
+OTHER COLUMNS (only with fields)
+hfi    Helios flow index (funding, OI, CVD), -100..100. Its OI part saturates; treat as rough.
+ar az  activity ratio and z-score (volume now vs baseline; ar < 0.5 = dead).
+vwap poc pocd vap   VWAP price, volume point of control, % from it, value-area position.
+macdh macds macdd   MACD histogram, signal label, divergence.
+vcc vcp             volatility clustering and change-point probability.
+obosd               overbought/oversold divergence. trh trend Hurst (> 0.5 trending).
+
+MARKET BLOCK (every response)
+os     how many of 23 large coins are down more than 7% in 24h (0..23). High = broad selloff.
+mti    micro trend: 5m + 1h moves of BTC, ETH, BNB, SOL, scaled. > 0 majors rising now.
+Mti    macro trend: weighted 5m/1h/6h/24h momentum of six majors, in %. > 0 market up.
+
+WHAT HAS HELD UP IN BACKTESTS (out of sample, last 2 years)
+- Buying a sharp turn up (hmiv > 0, r15m and r1h turning positive) in a coin whose
+  reg is BREAKDOWN or CRASH, especially when the whole market is down (os high, Mti < 0).
+- Fading stretched moves beat chasing them.
+- Shorts did not hold up. Edges are small (about +0.1% a trade): size small, always use a stop.

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

@@ -1,8 +1,9 @@
 ================================================================================
 HELIOS INDICATOR INDEX — AI AGENT REFERENCE
 ================================================================================
-# One entry per indicator. Format: file | data_field | type | range | purpose
-# All fields accessed via: indicators.<data_field>
+# START WITH 00_columns.txt: a short guide to every snapshot column id (hmi, reg, ob, hs...).
+# The entries below are longer guides, one per indicator. Format: file | data_field | type | range | purpose
+# data_field names here are the long names; snapshot columns use the short ids in 00_columns.txt.
 
 --------------------------------------------------------------------------------
 MOMENTUM / DIRECTION
@@ -22,10 +23,6 @@ regime.txt
   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
@@ -135,21 +132,10 @@ hfi_weights.txt
   Any weight < 0.10 = that data source is degraded.
 
 --------------------------------------------------------------------------------
-VOLATILITY / SQUEEZE
+VOLATILITY
 --------------------------------------------------------------------------------
-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]
@@ -200,7 +186,6 @@ DEPENDENCY MAP — KEY RELATIONSHIPS
   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)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pgnio/helios-mcp",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Helios MCP server: connect an AI agent to your Helios account to read markets and your portfolio and to trade on Hyperliquid. Most apps can use the hosted URL https://helios.pgn.io/mcp instead.",
   "license": "UNLICENSED",
   "homepage": "https://helios.pgn.io/?connect=ai",

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

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

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

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

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

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