diff --git a/README.md b/README.md
index 0f8782a..2a52945 100644
--- a/README.md
+++ b/README.md
@@ -788,10 +788,16 @@ acp trade --side short --token ETH --size 0.5 --price 4000 --post-only
 # Same shape for an equity, FX, or commodity perp — just change the symbol
 acp trade --side long --token <HL_MARKET_SYMBOL> --size 1 --leverage 3
 
-# Reduce-only (close part of a position)
-acp trade --side short --token BTC --size 0.01 --reduce-only
+# Close (part of) a position: --reduce-only with --side OPPOSITE to the position.
+# Closing a LONG is a SHORT order; closing a SHORT is a LONG order.
+acp trade --side short --token BTC --size 0.01 --reduce-only   # closes a BTC long
+acp trade --side long --token BTC --size 0.01 --reduce-only    # closes a BTC short
 ```
 
+> `--reduce-only` only shrinks an existing position — never set it when opening or
+> adding. If the side matches the position (or there's no position), Hyperliquid
+> rejects the order with "Reduce only order would increase position".
+
 **Hyperliquid — account & withdraw:**
 
 ```bash
diff --git a/src/commands/trade.ts b/src/commands/trade.ts
index 3551c17..203e59c 100644
--- a/src/commands/trade.ts
+++ b/src/commands/trade.ts
@@ -268,7 +268,13 @@ export function registerTradeCommands(program: Command): void {
     .option("--size <size>", "Perp order size in token units")
     .option("--leverage <n>", "Set leverage for this token before a perp order")
     .option("--isolated", "Use isolated margin when setting leverage", false)
-    .option("--reduce-only", "Only reduce an existing perp position", false)
+    .option(
+      "--reduce-only",
+      "Close/shrink an existing perp position. --side must be the OPPOSITE of the position " +
+        "(close a long with --side short, close a short with --side long). " +
+        "Never set this when opening or adding to a position — HL rejects it.",
+      false
+    )
     .option("--dry-run", "Preview the trade (route, size, margin, fees) without signing or submitting anything", false)
     .action(async (opts, cmd) => {
       const json = isJson(cmd);