strategies docs update

strategies/exposure_protector.md

@@ -2,30 +2,44 @@
 
 Defensive rebalancer that trims skew and protects exposure.
 
-## Best used when
+## Best Used When
 - one side of the book dominates the account
 - Hermes wants to reduce imbalance
 - the market is still tradable, but caution is needed
 - controlled rebalancing is more important than new alpha
 
-## Avoid when
+## Avoid When
 - the market is thin or chaotic
 - the venue is unstable
 - Hermes wants a pure entry strategy
 - frequent churn would be too expensive
 
-## Core parameters
-- `trail_distance_pct`: distance from price for execution
-- `rebalance_target_ratio`: desired base/value balance
-- `rebalance_step_ratio`: how much to move per action
-- `min_rebalance_seconds`: minimum time between actions
-- `min_price_move_pct`: minimum move before a new action
-- `min_order_notional_quote`: minimum quote notional for one action
-- `max_order_notional_quote`: optional quote notional cap for one action
+## How It Works
+- The strategy watches wallet drift and chooses the side needed to move the wallet back toward the target ratio.
+- `rebalance_target_ratio` is a value-share target for base, not a price target.
+- `rebalance_step_ratio` controls how far the strategy moves per action, but the actual side choice also depends on the current drift and hysteresis.
+- `min_rebalance_seconds` blocks repeat actions for a minimum wall-clock period.
+- `min_price_move_pct` blocks a new order if price has not moved enough since the last one.
+- `trail_distance_pct` sets the limit order distance from the current price once a side has been chosen.
+- `report()` and `render()` show the live drift, anchor, and cooldown state.
 
-## Hermes policy mapping
-- `risk_posture` controls caution vs aggression
-- `priority` controls urgency and cadence
+## Parameters
+- `trail_distance_pct`: Distance from the current price for the rebalance limit order.
+- `rebalance_target_ratio`: Target base value share between `0.0` and `1.0`. `0.5` means balanced by value.
+- `rebalance_step_ratio`: Fractional move size per action. Larger values rebalance faster but can churn more.
+- `min_order_notional_quote`: Minimum quote notional for one action.
+- `max_order_notional_quote`: Optional hard cap on quote notional for one action.
+- `order_spacing_ticks`: Declared in the schema, but currently not referenced by the execution path.
+- `cooldown_ticks`: Tick-based pause after a successful order.
+- `min_rebalance_seconds`: Wall-clock cooldown between rebalance actions.
+- `min_price_move_pct`: Minimum price movement required before the strategy will place another order.
+- `balance_tolerance`: Allowed deviation from the target before the strategy considers the wallet meaningfully out of balance.
+- `debug_orders`: Enables order-placement debug logging.
+
+## Hermes Policy Mapping
+- `risk_posture` controls caution vs aggression.
+- `priority` controls urgency and cadence.
+- In current code, `apply_policy()` rewrites `trail_distance_pct`, `rebalance_step_ratio`, `min_rebalance_seconds`, and `min_price_move_pct`.
 
 ## Notes
 - This strategy is passive until Hermes enables it.
@@ -34,3 +48,22 @@ Defensive rebalancer that trims skew and protects exposure.
 - `report().supervision` should be interpreted as a defensive attachment signal, not as a preferred replacement for a healthy grid during persistent trend continuation unless imbalance is genuinely severe.
 - live fee rates are used directly, and quote notional is the canonical sizing unit.
 - rebalance sizing now uses the shared strategy sizing helper so fee-aware quote bounds behave consistently with the other strategies.
+
+## Useful Example
+```json
+{
+  "trail_distance_pct": 0.025,
+  "rebalance_target_ratio": 0.55,
+  "rebalance_step_ratio": 0.2,
+  "min_order_notional_quote": 15,
+  "max_order_notional_quote": 60,
+  "order_spacing_ticks": 1,
+  "cooldown_ticks": 2,
+  "min_rebalance_seconds": 120,
+  "min_price_move_pct": 0.004,
+  "balance_tolerance": 0.04,
+  "debug_orders": false
+}
+```
+
+This is a conservative rebalancer that moves in smaller chunks, waits between actions, and only reacts when price has moved enough to justify another trim.

strategies/grid_trader.md

@@ -2,30 +2,49 @@
 
 Passive, structure-based liquidity strategy.
 
-## Best used when
+## Best Used When
 - price is range-bound or choppy
 - volatility is low to moderate
 - liquidity is decent
 - Hermes wants to harvest mean reversion inside a structure
 
-## Avoid when
+## Avoid When
 - trend is strong and persistent
 - event risk is high
 - liquidity is thin or chaotic
 - execution quality is poor
 
-## Core parameters
-- `grid_levels`: number of orders per side
-- `grid_step_pct`: base spacing between levels before inventory skew is applied
-- `inventory_rebalance_step_factor`: max fractional reduction applied to the rebalance side's step when the wallet is imbalanced
-- `recenter_pct`: when to rebuild the grid
-- `volatility_timeframe`: timeframe used for adaptive sizing
-- `order_notional_quote`: quote-currency notional target per order
-- `max_order_notional_quote`: optional quote-currency cap per order
+## How It Works
+- The strategy keeps a live base grid step, then derives side-specific buy and sell spacing from wallet imbalance.
+- ATR can override the configured base step. When ATR is available, `grid_step_pct` is a fallback rather than the final live step.
+- The live step is floored by `grid_step_min_pct` and capped by `grid_step_max_pct`.
+- Inventory skew only reduces the favored side. If the live step is already at the floor, the skew can disappear entirely.
+- Grid rebuilds use a separate recenter threshold built from `recenter_pct`, ATR, and the recenter clamps.
+- `report()` and `render()` expose the live base step plus the effective buy/sell split and current rebalance bias.
 
-## Hermes policy mapping
-- `risk_posture` adjusts grid spacing, levels, and recentering
-- `priority` adjusts aggressiveness and order cadence
+## Parameters
+- `grid_levels`: Number of order levels per side.
+- `grid_step_pct`: Base spacing when ATR is unavailable or zero. If ATR exists, this is only the fallback seed.
+- `volatility_timeframe`: ATR source timeframe used for live spacing and recenter calculations.
+- `volatility_multiplier`: Multiplier applied to ATR to produce the live step when ATR is available.
+- `grid_step_min_pct`: Minimum allowed live step. This floor also applies after inventory skew, so it can erase the visible skew if set too high.
+- `grid_step_max_pct`: Maximum allowed live step.
+- `inventory_rebalance_step_factor`: Maximum fractional reduction applied to the favored side. The actual reduction is `factor * imbalance`.
+- `order_notional_quote`: Target quote notional per order.
+- `max_order_notional_quote`: Optional hard cap on quote notional per order.
+- `recenter_pct`: Fallback recenter threshold when ATR is unavailable.
+- `recenter_atr_multiplier`: Multiplier applied to ATR to derive the live recenter threshold.
+- `recenter_min_pct`: Minimum recenter threshold floor.
+- `recenter_max_pct`: Maximum recenter threshold ceiling.
+- `trade_sides`: Intended side selection. `both` is the normal mode; other values are not a separate one-sided grid design and may be constrained by rebuild logic.
+- `dust_collect`: Allows the shared sizing helper to use leftover size more aggressively when a venue minimum would otherwise strand a small remainder.
+- `order_call_delay_ms`: Delay between sequential order placements during seeding or top-up.
+- `debug_orders`: Enables order-placement debug logging.
+
+## Hermes Policy Mapping
+- `risk_posture` adjusts grid spacing, levels, recentering, and cadence when policy is applied.
+- `priority` can override the risk posture to make the strategy more cautious or more aggressive.
+- In current code, `apply_policy()` rewrites `grid_step_pct`, `recenter_pct`, `grid_levels`, and `order_call_delay_ms` from policy.
 
 ## Notes
 - The strategy does not decide regime fit itself.
@@ -33,11 +52,35 @@ Passive, structure-based liquidity strategy.
 - Trader applies policy on reconcile.
 - `report().supervision` is descriptive, not imperative.
 - `side_capacity` and `inventory_pressure` describe the grid's current shape.
-- The grid step is now asymmetric when inventory drifts away from balance.
+- The grid step is asymmetric only when inventory is imbalanced enough to beat the minimum step floor.
 - If base value dominates quote value, the sell ladder is tightened to encourage rebalancing back into quote.
 - If quote value dominates base value, the buy ladder is tightened to encourage rebalancing back into base.
 - `inventory_rebalance_step_factor` is a cap, not a fixed override: small imbalances apply a small reduction and extreme imbalances apply up to the configured maximum reduction on the favored side only.
-- `report()` and `render()` expose the live base step plus the effective buy/sell step split and current rebalance bias.
 - ordinary directional conditions alone should not force a rebuild or switch.
 - live fee rates are used directly, and the quote notional is the canonical sizing unit.
-- quote sizing now flows through the shared strategy sizing helper, so grid and directional strategies use the same fee-aware notional rules.
+- quote sizing flows through the shared strategy sizing helper, so grid and directional strategies use the same fee-aware notional rules.
+
+## Useful Example
+```json
+{
+  "grid_levels": 6,
+  "grid_step_pct": 0.009,
+  "volatility_timeframe": "15m",
+  "volatility_multiplier": 1.5,
+  "grid_step_min_pct": 0.001,
+  "grid_step_max_pct": 0.03,
+  "inventory_rebalance_step_factor": 0.4,
+  "order_notional_quote": 25,
+  "max_order_notional_quote": 50,
+  "recenter_pct": 0.03,
+  "recenter_atr_multiplier": 0.35,
+  "recenter_min_pct": 0.002,
+  "recenter_max_pct": 0.03,
+  "trade_sides": "both",
+  "dust_collect": true,
+  "order_call_delay_ms": 150,
+  "debug_orders": false
+}
+```
+
+This is a practical low-to-moderate volatility setup. It keeps the minimum step low enough that inventory skew can still show up, while still letting ATR drive the live spacing when the market gets more active.

strategies/trend_follower.md

@@ -2,32 +2,44 @@
 
 Directional strategy for confirmed momentum.
 
-## Best used when
+## Best Used When
 - trend is strong and persistent
 - structure supports continuation
 - liquidity is normal
 - Hermes wants to follow momentum instead of fading it
 
-## Avoid when
+## Avoid When
 - price is range-bound
 - trend strength is weak or noisy
 - event risk is high
 - the market is too chaotic for clean continuation
 
-## Core parameters
-- `trade_side`: buy, sell, or both
-- `balance_target`: stop once the wallet reaches the target balance for the active side
-- `order_notional_quote`: quote-currency notional per order
-- `max_order_notional_quote`: optional quote notional cap per order
-- `dust_collect`: allow the last order on the funding side to consume leftover size when it would otherwise be stranded below the venue minimum
-- `entry_offset_pct`: offset from market for entries
-- `exit_offset_pct`: offset for exits or reversals
-- `cooldown_ticks`: pause between actions
-
-## Hermes policy mapping
+## How It Works
+- The strategy acts on the configured side, not on an internal trend model.
+- `trade_side` controls whether it can buy, sell, or accept either side. `both` is symmetric and depends on Hermes or the operator for direction.
+- `balance_target` is a wallet-allocation target, not a position-size target.
+- For `buy`, sub-`1.0` values stop the strategy once the base share of wallet value reaches the target.
+- For `sell`, sub-`1.0` values stop the strategy once the quote share reaches the target.
+- When an order would overshoot a sub-`1.0` target, the last order is clamped to the remaining gap.
+- `entry_offset_pct` sets the limit price offset for new entries.
+- `cooldown_ticks` pauses the next few ticks after a successful order.
+
+## Parameters
+- `trade_side`: Allowed side selection. `buy` and `sell` make it one-sided; `both` is symmetric and relies on Hermes for direction.
+- `balance_target`: Allocation target between `0.0` and `1.0`. `1.0` means keep trading until the funding side is exhausted. Lower values stop once the wallet reaches the requested mix.
+- `entry_offset_pct`: Limit-price offset used for new entries. Buy orders are placed above the last price, sell orders below it.
+- `exit_offset_pct`: Reserved for exit or reversal pricing in policy and supervision output. It is part of the contract even though the current entry path only uses `entry_offset_pct`.
+- `order_notional_quote`: Target quote notional per order.
+- `max_order_notional_quote`: Optional hard cap on quote notional per order.
+- `dust_collect`: Lets the shared sizing helper consume leftover size more aggressively when a venue minimum would otherwise strand a small remainder.
+- `cooldown_ticks`: Number of ticks to wait after a successful order before the strategy can act again.
+- `debug_orders`: Enables order-placement debug logging.
+
+## Hermes Policy Mapping
 - Hermes controls whether the side is active.
 - Hermes may set `balance_target` to define how far the wallet should rotate.
 - Hermes may set the quote notional and offsets.
+- `apply_policy()` currently records the derived values but does not rewrite the config the way the grid and exposure strategies do.
 
 ## Notes
 - Hermes decides when trend following is allowed.
@@ -39,3 +51,20 @@ Directional strategy for confirmed momentum.
 - In `sell` mode, values below `1.0` target the quote share of wallet value. Example: `0.5` stops near a 50/50 quote-base split.
 - When an order would overshoot a sub-`1.0` `balance_target`, the final order is clamped to the remaining target gap instead of sending the full configured notional.
 - live fee rates are used directly, so the strategy does not need a configured fee fallback.
+
+## Useful Example
+```json
+{
+  "trade_side": "buy",
+  "balance_target": 0.8,
+  "entry_offset_pct": 0.0035,
+  "exit_offset_pct": 0.002,
+  "order_notional_quote": 25,
+  "max_order_notional_quote": 40,
+  "dust_collect": true,
+  "cooldown_ticks": 3,
+  "debug_orders": false
+}
+```
+
+This is a practical long-only accumulation setup. It keeps buying until the wallet is roughly 80 percent base by value, uses a modest entry offset, and avoids oversized last orders.