Add capital efficiency risk simulation

scripts/README.md

@@ -80,8 +80,32 @@ node scripts/run-scenario.cjs hub_only_11
 node scripts/run-scenario.cjs --scenario full_quote_1_56_137
 node scripts/run-scenario.cjs bridge_shock_137_56
 node scripts/run-scenario.cjs micro_support_usd_wrappers_1_56_137
+node scripts/run-scenario.cjs crash_40pct_external_asset
+node scripts/run-scenario.cjs high_vol_sigma_spike
+node scripts/run-scenario.cjs bank_run_redemption_spike
+node scripts/run-scenario.cjs --optimizer leverage_sweep_1x_to_4x
 ```
 
 **Output:** JSON scorecard including: `capture_mean`, `churn_mean`, `drain_half_life_epochs`, `path_concentration_index`; `intervention_cost_total` / `intervention_cost_inject_total` / `intervention_cost_withdraw_total` / `intervention_cost_by_chain` / `intervention_cost_per_1M_volume`; `micro_trade_count` / `micro_trade_volume_total` / `micro_trade_gas_cost_total`; `peak_deviation_bps` (post-arb), `peak_deviation_bps_pre_arb`, `peak_deviation_bps_post_arb`, `peak_deviation_bps_post_bot`; `arb_volume_total`, `arb_profit_total` (execution-based, not mid). See [docs/12-sim-scorecard.md](../docs/12-sim-scorecard.md) and [config/scorecard-schema.json](../config/scorecard-schema.json).
 
+When `capitalEfficiency.enabled = true`, output also includes Monte Carlo capital-risk metrics: `roi_mean`, `roi_p05`, `roi_p95`, `pnl_distribution`, `max_drawdown_p95`, `liquidation_probability`, `peg_deviation_frequency`, `external_liquidity_floor_violations`, `volatility_throttle_events`, and `spread_adjustment_events`. Optimizer mode emits ranked parameter candidates and never treats leverage above the configured hard ceiling as deployable.
+
 **Orderflow:** Trade sizes use `distribution: "uniform"` by default. Scenario schema supports `lognormal` / `pareto` for skewed (many small + occasional whale) flows; implement in `sampleTrade()` when needed.
+
+---
+
+## validate-capital-efficiency.cjs
+
+Runs CI-style checks for the simulation-only capital efficiency overlay:
+
+- JSON parse for policy, schemas, and scenarios
+- Baseline scenario remains capital-overlay free
+- Stress scenarios emit capital risk fields
+- Deterministic repeat check
+- Optimizer deployable candidates respect `maxDeployableLeverage`
+
+**Run:**
+
+```bash
+node scripts/validate-capital-efficiency.cjs
+```