docs: note inventory control is stripped, point to Avellaneda-Stoikov

calculate_quotes_fast has no inventory adjustment � it skews quotes purely
from the gap-resistance alpha signal. Added prominent notes in both the
docstring and README explaining:

- Inventory control is intentionally absent
- Users must compute a reservation mid before calling calculate_quotes_fast
- Formula: reservation_mid = fair_mid + alpha - gamma * sigma^2 * inventory
- Reference: Avellaneda & Stoikov (2008)

Also added 'No inventory control' to the known limitations bullet list.

Made-with: Cursor

Author: alihaskar

README.md

@@ -41,9 +41,38 @@ Bybit public WS
 
 ---
 
+## Inventory control — bring your own
+
+`calculate_quotes_fast` has **no inventory control**. It skews quotes purely based on the
+gap-resistance alpha signal and does not penalise a growing position. Running it as-is will
+expose you to adverse selection and unbounded inventory risk.
+
+To use this as a proper market-making strategy, compute a **reservation mid** that combines
+the alpha signal with an inventory penalty before calling `calculate_quotes_fast`:
+
+```
+reservation_mid = fair_mid + alpha_adjustment - gamma * sigma² * inventory
+```
+
+where:
+- `fair_mid` — raw exchange mid price
+- `alpha_adjustment` — your short-term price prediction (e.g. derived from the gap signal)
+- `gamma` — risk-aversion / inventory-penalty coefficient (tune to your position limit)
+- `sigma` — short-term realised volatility
+- `inventory` — current net position (positive = long, negative = short)
+
+Pass `reservation_mid` as the `mid_price` argument and the spread will automatically
+centre around an inventory-aware fair value instead of the raw mid.
+
+The canonical reference for this approach is **Avellaneda & Stoikov (2008)**,
+"High-frequency trading in a limit order book."
+
+---
+
 ## Known limitations / quirks
 
 - **No backtested edge.** The gap-probability signal is a microstructure heuristic. It has not been statistically validated. Treat this as a reference implementation, not a proven profitable strategy.
+- **No inventory control.** See the section above. You must implement your own reservation-price adjustment to run this safely in production.
 - **Bybit only.** The WS and REST code is Bybit-specific (v5 API).
 - **Tick size must match your symbol.** Pass `tick_size` both in `.env` and to `TradingNode.start_stream(tick_size=...)`. Default is `0.10` (BTCUSDT spot). Other symbols need their correct tick size.
 - **PostOnly orders only.** The bot never crosses the spread. If the market is too fast, orders are amended rather than re-submitted.

src/gap_mm/engine.py

@@ -91,6 +91,25 @@ def calculate_quotes_fast(
     Returns
     -------
     (bid_price, ask_price, bid_edge_ticks, ask_edge_ticks, spread_ticks)
+
+    NOTE — inventory control has been intentionally stripped out.
+    This function only skews quotes based on the gap-resistance alpha signal.
+    To avoid adverse selection and control position risk you should implement
+    your own inventory adjustment before calling this function, e.g.
+    Avellaneda-Stoikov reservation price:
+
+        reservation_mid = fair_mid + alpha_adjustment - gamma * sigma^2 * inventory
+
+    where:
+        fair_mid          = raw mid price
+        alpha_adjustment  = signal-derived short-term price prediction
+        gamma             = risk-aversion coefficient
+        sigma             = realized volatility
+        inventory         = current net position (positive = long, negative = short)
+
+    Pass the adjusted reservation_mid as ``mid_price`` to have the spread
+    automatically centred around a position-aware fair value, rather than the
+    raw exchange mid.
     """
     if confidence == CONF_HIGH or confidence == CONF_MED:
         if signal == SIGNAL_UP: