diff --git a/docs/api.md b/docs/api.md
index ff9881b..aa21b97 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1180,12 +1180,35 @@ condition is true simultaneously fire their `then` action.
 | `rule.when` | A `Condition` tree (see below) |
 | `rule.then.side` | `"buy"` or `"sell"` |
 | `rule.then.quantity` | Fixed decimal string (e.g. `"0.001"`) or dynamic `Expr` object |
+| `rule.then.reverse` | `true` to reverse through flat into a new position (default `false`) |
 
 **Closing orders:** When an order's side is opposite to the current position (sell while long,
 or buy while short), the engine automatically uses the full position quantity, ignoring the
 configured sizing. This ensures clean position closes. When flat or adding to an existing
 position, the configured quantity is used as-is.
 
+**Reversals:** Set `"reverse": true` on a rule action to close the existing position *and*
+immediately open a new one in the opposite direction. The submitted order quantity becomes
+`existing_position_qty + configured_quantity`, and barter splits the fill proportionally —
+the first portion closes the old position, the remainder opens the new one. When there is no
+opposing position `reverse` has no effect and the configured quantity is used normally.
+
+Example — EMA crossover strategy that always holds a position (long or short):
+```json
+{
+  "rules": [
+    {
+      "when": { "kind": "ema_crossover", "fast": 9, "slow": 21, "direction": "up" },
+      "then": { "side": "buy", "quantity": "0.001", "reverse": true }
+    },
+    {
+      "when": { "kind": "ema_crossover", "fast": 9, "slow": 21, "direction": "down" },
+      "then": { "side": "sell", "quantity": "0.001", "reverse": true }
+    }
+  ]
+}
+```
+
 **Warm-up:** Indicators require historical candles to compute. The executor automatically
 pre-loads candles before `starts_at` based on the maximum indicator period in the strategy. You do
 not need to extend `starts_at` manually.