docs(v2.0.0-alpha.5): rich math+physics background per chapter, fix notebook download links

Each of the eight v2.0 algorithm pages (bsde, pde, stochastic_control,
quadratic_impact_control, mckean_vlasov, agent_based, robust_drift,
generative_calibration_hooks) gains:

- A dedicated 'Mathematical background' section with the central theorem
  (Pardoux-Peng, Sznitman propagation of chaos, Pontryagin-Bismut,
  Huber-IRLS, Gretton MMD, Kolmogorov forward, etc.), key derivations
  and the analytic closed-form solution that the unit tests target.
- An 'Applications' / 'Why it matters' paragraph listing concrete
  research and engineering use-cases so newcomers grasp the value of
  each primitive.
- A repaired companion-notebook block: the broken relative path
  '../../examples/notebooks/...ipynb' (which 404s on RTD) is replaced
  by an explicit GitHub blob (view) + raw (download) URL pair.

Sphinx now builds the full doc set with zero new warnings.

docs/source/algorithms/mckean_vlasov.rst

@@ -1,9 +1,85 @@
 McKean–Vlasov — propagation of chaos
 ====================================
 
-Interacting-particle Euler scheme for $dX_t = θ(\bar X_t - X_t) dt + σ dW_t$ (`mean_reverting_mckean_vlasov`).  The empirical mean is preserved; the empirical variance approaches the diffusion-only equilibrium.
+A **McKean–Vlasov SDE** is a stochastic differential equation whose drift and diffusion depend
+on the *law* of the solution itself:
 
-.. note:: Companion executed notebook: `14_mckean_vlasov.ipynb <../../examples/notebooks/14_mckean_vlasov.ipynb>`_
+.. math::
+
+   dX_t \;=\; b\bigl(t, X_t, \mathcal{L}(X_t)\bigr)\, dt \;+\; \sigma\bigl(t, X_t, \mathcal{L}(X_t)\bigr)\, dW_t,
+   \qquad X_0 \sim \mu_0 .
+
+It is the formal $N \to \infty$ limit of an exchangeable system of $N$ interacting diffusions
+
+.. math::
+
+   dX^{i,N}_t \;=\; b\!\Bigl(t, X^{i,N}_t, \tfrac1N\!\sum_{j=1}^N \delta_{X^{j,N}_t}\Bigr)\, dt
+              \;+\; \sigma\!\Bigl(t, X^{i,N}_t, \tfrac1N\!\sum_{j=1}^N \delta_{X^{j,N}_t}\Bigr)\, dW^i_t .
+
+The primitive shipped here, `mean_reverting_mckean_vlasov`, simulates the canonical example
+
+.. math::
+
+   dX_t \;=\; \theta\bigl(\bar X_t - X_t\bigr)\, dt \;+\; \sigma\, dW_t,
+   \qquad \bar X_t = \mathbb{E}[X_t],
+
+with the symmetric Euler particle scheme $X^{i,N}_{k+1} = X^{i,N}_k + \theta(\bar X^N_k - X^{i,N}_k)\Delta t + \sigma\sqrt{\Delta t}\,\xi^i_k$.
+
+Mathematical background
+-----------------------
+
+**Sznitman's propagation of chaos (1991).**  Under standard Lipschitz assumptions on $b, \sigma$ in
+$(x, \mu)$ (the $\mu$ argument equipped with the Wasserstein distance $W_2$), the empirical
+measure $\mu^N_t = \tfrac1N \sum_i \delta_{X^{i,N}_t}$ converges weakly to the deterministic flow
+$\mathcal{L}(X_t)$, and any fixed sub-system of $k$ particles becomes asymptotically independent:
+
+.. math::
+
+   \sup_{0 \le t \le T} \, \mathbb{E}\bigl[\,W_2^2\!\bigl(\mu^N_t,\, \mathcal{L}(X_t)\bigr)\bigr]
+   \;\le\; \frac{C(T)}{N^{2/(d+4)}} .
+
+**Density flow (nonlinear Fokker–Planck).**  The marginal density $\rho_t = \mathrm{law}(X_t)$
+satisfies the *nonlinear* PDE
+
+.. math::
+
+   \partial_t \rho_t \;+\; \nabla\!\cdot\!\bigl(b(t, x, \rho_t)\, \rho_t\bigr)
+   \;=\; \tfrac12\, \nabla^2\!:\!\bigl(\sigma\sigma^\top(t, x, \rho_t)\, \rho_t\bigr).
+
+**Closed-form for the mean-reverting case.**  Taking expectation of the SDE gives
+$\dot{\bar X}_t = 0$, so the population mean is *exactly preserved*: $\bar X_t \equiv \bar X_0$.
+The deviation $\widetilde X^i_t := X^{i,N}_t - \bar X_0$ then solves a standard Ornstein–Uhlenbeck
+SDE, so each marginal is Gaussian with
+
+.. math::
+
+   \mathbb{E}[X_t] \;=\; \bar X_0,
+   \qquad
+   \mathrm{Var}(X_t) \;=\; \mathrm{Var}(X_0)\, e^{-2\theta t} \;+\; \frac{\sigma^2}{2\theta}\bigl(1 - e^{-2\theta t}\bigr)
+   \;\xrightarrow[t\to\infty]{}\; \frac{\sigma^2}{2\theta}.
+
+The companion notebook checks both the mean conservation and the variance asymptote.
+
+**Connection with mean-field BSDEs.**  Coupling the McKean–Vlasov forward SDE with a backward
+equation $-dY_t = f(t, X_t, Y_t, Z_t, \mathcal{L}(X_t, Y_t))\, dt - Z_t\, dW_t$ produces the
+*mean-field BSDE* of Carmona–Delarue (2018), itself the probabilistic representation of the
+HJB side of mean-field games (cf. :doc:`stochastic_control`).
+
+Why it matters
+--------------
+
+* **Mean-field games.**  At the Nash equilibrium of a symmetric $N$-player game, each player's
+  state follows a McKean–Vlasov SDE in which the population law $\mu_t$ is the consistent
+  fixed point of every player's best response.  This is the master tool of Lasry–Lions theory
+  for systemic-risk modelling, optimal execution and price formation.
+* **Statistical physics.**  Vlasov, Boltzmann, and granular-media equations all arise as
+  density flows of mean-field particle systems; the same Euler scheme estimates their solutions.
+* **Generative modelling.**  Stein-variational gradient descent and score-based diffusion can
+  be analysed as McKean–Vlasov gradient flows on $W_2$.
+
+.. note::
+   📓 **Companion notebook** — `view on GitHub <https://github.com/ThotDjehuty/optimiz-rs/blob/main/examples/notebooks/14_mckean_vlasov.ipynb>`_
+   · `download .ipynb <https://raw.githubusercontent.com/ThotDjehuty/optimiz-rs/main/examples/notebooks/14_mckean_vlasov.ipynb>`_
 
 14 — McKean–Vlasov mean-reverting dynamics
 ==========================================