docs: enhance ReadTheDocs with visualization outputs and GitHub links

docs/source/algorithms/grid_search.md

@@ -306,6 +306,20 @@ plt.title('Grid Search: Loss Surface')
 plt.savefig('grid_search_heatmap.png', dpi=150)
 ```
 
+**Output:**
+
+Produces a 2D heatmap showing the loss landscape across different hyperparameter combinations:
+- **X-axis**: Dropout rate values
+- **Y-axis**: Learning rate values
+- **Color intensity**: Loss values (darker = lower loss = better performance)
+
+This visualization helps identify optimal parameter regions and understand parameter interactions.
+
+📓 **Real-World Examples**: See [04_real_world_applications.ipynb](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/04_real_world_applications.ipynb) for grid search applied to:
+- Neural network hyperparameter tuning
+- Portfolio optimization
+- Trading strategy parameter selection
+
 ---
 
 ## Combining with Other Methods

docs/source/algorithms/hmm.md

@@ -448,6 +448,14 @@ plt.tight_layout()
 plt.savefig('hmm_states.png', dpi=150)
 ```
 
+**Output:**
+
+This visualization creates a two-panel plot:
+- **Top panel**: Returns time series showing price movements
+- **Bottom panel**: Decoded state sequence highlighting regime transitions (e.g., Bull/Bear markets)
+
+For complete examples with regime detection on real market data, see the [HMM Tutorial notebook](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/01_hmm_tutorial.ipynb).
+
 ### Transition Diagram
 
 ```python
@@ -469,6 +477,19 @@ plt.title('HMM Transition Diagram')
 plt.savefig('hmm_transitions.png', dpi=150)
 ```
 
+**Output:**
+
+Generates a directed graph visualization showing:
+- **Nodes**: Hidden states (e.g., State 0, State 1)
+- **Edges**: Transition probabilities between states (labeled with probability values)
+- Only transitions with probability > 0.01 are shown for clarity
+
+📓 **Full Tutorial**: Explore [01_hmm_tutorial.ipynb](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/01_hmm_tutorial.ipynb) for hands-on examples including:
+- Multi-state regime detection
+- Volatility clustering analysis
+- Mean-reversion regime identification
+- Viterbi decoding in financial time series
+
 ---
 
 ## Applications

docs/source/algorithms/mean_field_games.md

@@ -237,6 +237,14 @@ plt.tight_layout()
 plt.savefig('mfg_heatmaps.png', dpi=150)
 ```
 
+**Output:**
+
+This code generates two side-by-side heatmaps:
+- **Left plot**: Population density `m(x,t)` evolution over space and time
+- **Right plot**: Value function `u(x,t)` showing optimal value at each position and time
+
+For interactive visualization with complete outputs, see the [Mean Field Games Tutorial notebook](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/mean_field_games_tutorial.ipynb) on GitHub.
+
 ### Time Slices
 
 ```python
@@ -256,6 +264,12 @@ plt.grid(True, alpha=0.3)
 plt.savefig('mfg_time_slices.png', dpi=150)
 ```
 
+**Output:**
+
+This produces a line plot showing population density profiles at 5 different time points (t=0.0, 0.25, 0.5, 0.75, 1.0), illustrating how the population distribution evolves from initial to terminal conditions.
+
+📓 **Complete Examples**: See the [Mean Field Games Tutorial](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/mean_field_games_tutorial.ipynb) for interactive visualizations with real numerical solutions.
+
 ---
 
 ## Performance
@@ -351,7 +365,7 @@ Good choices for `m0`:
 ## Notebook Tutorial
 
 For a complete walkthrough with validated outputs and visualizations, see the 
-Mean Field Games Tutorial notebook at `examples/notebooks/mean_field_games_tutorial.ipynb`.
+[Mean Field Games Tutorial notebook](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/mean_field_games_tutorial.ipynb) on GitHub.
 
 The notebook demonstrates:
 
@@ -361,4 +375,4 @@ The notebook demonstrates:
 - Interpreting convergence diagnostics
 - Comparing congestion levels
 
-Audit documentation is available at `docs/MFG_TUTORIAL_COMPLETE.md`.
+Audit documentation is available at [`docs/MFG_TUTORIAL_COMPLETE.md`](https://github.com/ThotDjehuty/optimiz-r/blob/main/docs/MFG_TUTORIAL_COMPLETE.md).

docs/source/api/optimal_control.md

@@ -114,4 +114,4 @@ log_likelihoods = result.get_log_likelihoods()
 
 **Conceptual picture:** Kalman filtering = prediction (dynamics prior) + correction (measurement residual). EKF linearizes $f, h$; UKF propagates sigma points for better nonlinear fidelity. RTS smoothing runs backward in time to refine all past states.
 
-See `examples/notebooks/03_optimal_control_tutorial.ipynb` for end-to-end usage combining HJB thresholds, OU estimation, and filtering.
+See [`examples/notebooks/03_optimal_control_tutorial.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/03_optimal_control_tutorial.ipynb) for end-to-end usage combining HJB thresholds, OU estimation, and filtering.

docs/source/benchmarks.md

@@ -11,8 +11,8 @@ These results come from the Rust backends (release build) versus SciPy’s `diff
 
 **How to reproduce**
 
-- Run `examples/notebooks/05_performance_benchmarks.ipynb` (validated in CI) to regenerate figures and raw CSV metrics.
-- Or from the repo root, run `make benchmark` for the Rust-side microbenchmarks (no Python overhead).
+- Run [`examples/notebooks/05_performance_benchmarks.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/05_performance_benchmarks.ipynb) (validated in CI) to regenerate figures and raw CSV metrics.
+- Or from the [repo root](https://github.com/ThotDjehuty/optimiz-r), run `make benchmark` for the Rust-side microbenchmarks (no Python overhead).
 - To compare against SciPy, set `SCIPY_BASELINE=1` in the notebook; it records wall-clock times and success percentages side by side.
 
 **What the notebook plots**

docs/source/examples.md

@@ -108,15 +108,17 @@ print("Half-life:", estimate_half_life_py(returns))
 
 ## Notebooks
 
-- Differential Evolution: `examples/notebooks/03_differential_evolution_tutorial.ipynb`
-- Mean Field Games: `examples/notebooks/mean_field_games_tutorial.ipynb`
-- HMM: `examples/notebooks/01_hmm_tutorial.ipynb`
-- MCMC: `examples/notebooks/02_mcmc_tutorial.ipynb`
-- Optimal Control & Kalman: `examples/notebooks/03_optimal_control_tutorial.ipynb`
-- Performance benchmarks: `examples/notebooks/05_performance_benchmarks.ipynb`
+Explore interactive tutorials on GitHub:
+
+- **Differential Evolution**: [`03_differential_evolution_tutorial.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/03_differential_evolution_tutorial.ipynb)
+- **Mean Field Games**: [`mean_field_games_tutorial.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/mean_field_games_tutorial.ipynb)
+- **HMM**: [`01_hmm_tutorial.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/01_hmm_tutorial.ipynb)
+- **MCMC**: [`02_mcmc_tutorial.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/02_mcmc_tutorial.ipynb)
+- **Optimal Control & Kalman**: [`03_optimal_control_tutorial.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/03_optimal_control_tutorial.ipynb)
+- **Performance Benchmarks**: [`05_performance_benchmarks.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/05_performance_benchmarks.ipynb)
 
 ## Contribute Examples
 
-1. Fork the repository and add notebooks under `examples/notebooks/`
+1. Fork the [repository](https://github.com/ThotDjehuty/optimiz-r) and add notebooks under `examples/notebooks/`
 2. Keep dependencies minimal (NumPy/Matplotlib preferred)
 3. Ensure the notebook runs end-to-end before submitting a PR

docs/source/mfg_tutorial.md

@@ -1,6 +1,6 @@
 # Mean Field Games Tutorial (Production)
 
-This page summarizes the full MFG tutorial notebook (`examples/notebooks/mean_field_games_tutorial.ipynb`) and the accompanying audit in `docs/MFG_TUTORIAL_COMPLETE.md`.
+This page summarizes the full MFG tutorial notebook ([`mean_field_games_tutorial.ipynb`](https://github.com/ThotDjehuty/optimiz-r/blob/main/examples/notebooks/mean_field_games_tutorial.ipynb)) and the accompanying audit in [`docs/MFG_TUTORIAL_COMPLETE.md`](https://github.com/ThotDjehuty/optimiz-r/blob/main/docs/MFG_TUTORIAL_COMPLETE.md).
 
 ## What the notebook demonstrates