docs: refine documentation

Signed-off-by: Jérôme Benoit <jerome.benoit@piment-noir.org>

diff --git a/README.md b/README.md
index d90a7cd8987cc490d2e049638a8b81e001c0f44d..233cb0cb1e176001b0a82e46b1c6e4ad758ef1cf 100644 (file)
--- a/README.md
+++ b/README.md
@@ -43,7 +43,7 @@ docker compose up -d --build
 | leverage                                             | proposed_leverage | float [1.0, max_leverage]                                                                                                        | Leverage. Fallback to proposed_leverage for the pair.                                                                                                                                                      |
 | _Exit pricing_                                       |                   |                                                                                                                                  |                                                                                                                                                                                                            |
 | exit_pricing.trade_price_target                      | `moving_average`  | enum {`moving_average`,`interpolation`,`weighted_interpolation`}                                                                 | Trade NATR computation method.                                                                                                                                                                             |
-| exit_pricing.thresholds_calibration.decline_quantile | 0.90              | float (0,1)                                                                                                                      | PNL decline quantile threshold.                                                                                                                                                                            |
+| exit_pricing.thresholds_calibration.decline_quantile | 0.90              | float (0,1)                                                                                                                      | PnL decline quantile threshold.                                                                                                                                                                            |
 | _Reversal confirmation_                              |                   |                                                                                                                                  |                                                                                                                                                                                                            |
 | reversal_confirmation.lookback_period                | 0                 | int >= 0                                                                                                                         | Prior confirming candles; 0 = none.                                                                                                                                                                        |
 | reversal_confirmation.decay_ratio                    | 0.5               | float (0,1]                                                                                                                      | Geometric per-candle relaxation factor.                                                                                                                                                                    |

diff --git a/ReforceXY/reward_space_analysis/README.md b/ReforceXY/reward_space_analysis/README.md
index 901514fa88dec8b286a575d5e67f1538959258fc..e5f677f7917096bafbfc22b6958a9efdaad7ccb4 100644 (file)
--- a/ReforceXY/reward_space_analysis/README.md
+++ b/ReforceXY/reward_space_analysis/README.md
@@ -278,24 +278,24 @@ r* = r - grace    if exit_plateau and r >  grace
 r* = r            if not exit_plateau
 ```
 
-| Mode      | Multiplier applied to base_factor \* pnl \* pnl_factor \* efficiency_factor | Monotonic | Notes                                       |
-| --------- | --------------------------------------------------------------------------- | --------- | ------------------------------------------- |
-| legacy    | step: ×1.5 if r\* ≤ 1 else ×0.5                                             | No        | Non-monotonic legacy mode (not recommended) |
-| sqrt      | 1 / sqrt(1 + r\*)                                                           | Yes       | Sub-linear decay                            |
-| linear    | 1 / (1 + slope \* r\*)                                                      | Yes       | slope = `exit_linear_slope`                 |
-| power     | (1 + r\*)^(-alpha)                                                          | Yes       | alpha = -ln(tau)/ln(2); tau=1 ⇒ alpha=0     |
-| half_life | 2^(- r\* / hl)                                                              | Yes       | hl = `exit_half_life`; r\*=hl ⇒ factor ×0.5 |
+| Mode      | Multiplier applied to base_factor \* pnl \* pnl_factor \* efficiency_factor | Monotonic | Notes                                       | Use Case                             |
+| --------- | --------------------------------------------------------------------------- | --------- | ------------------------------------------- | ------------------------------------ |
+| legacy    | step: ×1.5 if r\* ≤ 1 else ×0.5                                             | No        | Non-monotonic legacy mode (not recommended) | Backward compatibility only          |
+| sqrt      | 1 / sqrt(1 + r\*)                                                           | Yes       | Sub-linear decay                            | Gentle long-trade penalty            |
+| linear    | 1 / (1 + slope \* r\*)                                                      | Yes       | slope = `exit_linear_slope`                 | Balanced duration penalty (default)  |
+| power     | (1 + r\*)^(-alpha)                                                          | Yes       | alpha = -ln(tau)/ln(2); tau=1 ⇒ alpha=0     | Tunable decay rate via tau parameter |
+| half_life | 2^(- r\* / hl)                                                              | Yes       | hl = `exit_half_life`; r\*=hl ⇒ factor ×0.5 | Time-based exponential discount      |
 
 ### Transform Functions
 
-| Transform  | Formula            | Range   | Characteristics   | Use Case                      |
-| ---------- | ------------------ | ------- | ----------------- | ----------------------------- |
-| `tanh`     | tanh(x)            | (-1, 1) | Smooth sigmoid    | Balanced transforms (default) |
-| `softsign` | x / (1 + \|x\|)    | (-1, 1) | Linear near 0     | Less aggressive saturation    |
-| `arctan`   | (2/π) \* arctan(x) | (-1, 1) | Slower saturation | Wide dynamic range            |
-| `sigmoid`  | 2σ(x) - 1          | (-1, 1) | Standard sigmoid  | Generic shaping               |
-| `asinh`    | x / sqrt(1 + x^2)  | (-1, 1) | Outlier robust    | Extreme stability             |
-| `clip`     | clip(x, -1, 1)     | [-1, 1] | Hard clipping     | Preserve linearity            |
+| Transform  | Formula                          | Range   | Characteristics   | Use Case                      |
+| ---------- | -------------------------------- | ------- | ----------------- | ----------------------------- |
+| `tanh`     | tanh(x)                          | (-1, 1) | Smooth sigmoid    | Balanced transforms (default) |
+| `softsign` | x / (1 + \|x\|)                  | (-1, 1) | Linear near 0     | Less aggressive saturation    |
+| `arctan`   | (2/π) \* arctan(x)               | (-1, 1) | Slower saturation | Wide dynamic range            |
+| `sigmoid`  | 2σ(x) - 1, σ(x) = 1/(1 + e^(-x)) | (-1, 1) | Standard sigmoid  | Generic shaping               |
+| `asinh`    | x / sqrt(1 + x^2)                | (-1, 1) | Outlier robust    | Extreme stability             |
+| `clip`     | clip(x, -1, 1)                   | [-1, 1] | Hard clipping     | Preserve linearity            |
 
 ### Skipping Feature Analysis