update2

docs/README.md

@@ -10,3 +10,6 @@ Conventions:
 - Append new entries instead of overwriting old ones.
 - Record exact config file and key overrides when possible.
 - Keep metrics in the order: avg_ks / avg_jsd / avg_lag1_diff.
+
+Tools:
+- `example/diagnose_ks.py` for per-feature KS + CDF plots.

docs/decisions.md

@@ -33,3 +33,9 @@
   - `example/sample.py`
   - `example/export_samples.py`
   - `example/config.json`
+
+## 2026-01-26 — Per-feature KS diagnostics
+- **Decision**: Add a per-feature KS/CDF diagnostic script to pinpoint KS failures (tails, boundary pile-up, shifts).
+- **Why**: Avoid blind reweighting and find the specific features causing KS to stay high.
+- **Files**:
+  - `example/diagnose_ks.py`