Align HowToLens documentation with the current course

docs/howtolens/chapter_1_introduction.md

@@ -6,29 +6,26 @@ In chapter 1, we introduce you to strong gravitational lensing and the core **Py
 
 The chapter contains the following tutorials:
 
-[Tutorial 0: Visualization](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_1_introduction/tutorial_0_visualization.ipynb)
+[Tutorial 0: Visualization](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_1_introduction/tutorial_0_visualization.ipynb)
 \- Setting up **PyAutoLens**'s visualization library.
 
-[Tutorial 1: Grids And Galaxies](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_1_introduction/tutorial_1_grids_and_galaxies.ipynb)
+[Tutorial 1: Grids And Galaxies](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_1_introduction/tutorial_1_grids_and_galaxies.ipynb)
 \- Using grids of (y,x) coordinates with galaxies made up of light profiles.
 
-[Tutorial 2: Ray Tracing](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_1_introduction/tutorial_2_ray_tracing.ipynb)
+[Tutorial 2: Ray Tracing](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_1_introduction/tutorial_2_ray_tracing.ipynb)
 \- Using grids, galaxies and mass profiles to perform strong lens ray-tracing.
 
-[Tutorial 3: More Ray Tracing](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_1_introduction/tutorial_3_more_ray_tracing.ipynb)
+[Tutorial 3: More Ray Tracing](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_1_introduction/tutorial_3_more_ray_tracing.ipynb)
 \- Advanced strong lens ray-tracing.
 
-[Tutorial 4: Point Sources](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_1_introduction/tutorial_4_point_sources.ipynb)
+[Tutorial 4: Point Sources](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_1_introduction/tutorial_4_point_sources.ipynb)
 \- How lensing calculations change when the source galaxy is a point source (e.g. a quasar).
 
-[Tutorial 5: Lensing Formalism](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_1_introduction/tutorial_5_lensing_formalism.ipynb)
-\- The algebraic lensing formalism used to describe strong lensing.
-
-[Tutorial 6: Data](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_1_introduction/tutorial_6_data.ipynb)
+[Tutorial 5: Data](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_1_introduction/tutorial_5_data.ipynb)
 \- Loading and inspecting telescope imaging data of a strong lens.
 
-[Tutorial 7: Fitting](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_1_introduction/tutorial_7_fitting.ipynb)
+[Tutorial 6: Fitting](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_1_introduction/tutorial_6_fitting.ipynb)
 \- Fitting data with a strong lens model.
 
-[Tutorial 8: Summary](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_1_introduction/tutorial_8_summary.ipynb)
+[Tutorial 7: Summary](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_1_introduction/tutorial_7_summary.ipynb)
 \- A summary of the chapter.

docs/howtolens/chapter_2_lens_modeling.md

@@ -1,39 +1,26 @@
 # Chapter 2: Lens Modeling
 
-In chapter 2, we'll take you through how to model strong lenses using a non-linear search, ending with how
-searches are chained together into automated lens modeling pipelines.
+In chapter 2, we model strong lenses using a non-linear search, learn why fits can fail, and chain searches to fit different components in stages.
 
 The chapter contains the following tutorials:
 
-[Tutorial 1: Non-linear Search](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_2_lens_modeling/tutorial_1_non_linear_search.ipynb)
-\- How a non-linear search is used to fit a lens model and the concepts of a parameter space and priors.
+[Tutorial 1: Non-linear Search](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_2_lens_modeling/tutorial_1_non_linear_search.ipynb)
+\- Use a non-linear search to explore model parameters and priors.
 
-[Tutorial 2: Practicalities](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_2_lens_modeling/tutorial_2_practicalities.ipynb)
-\- Practicalities of performing model-fitting, like how to inspect the results on your hard-disk.
+[Tutorial 2: Practicalities](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_2_lens_modeling/tutorial_2_practicalities.ipynb)
+\- Configure a search, follow its progress and inspect its saved results.
 
-[Tutorial 3: Realism and Complexity](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_2_lens_modeling/tutorial_3_realism_and_complexity.ipynb)
-\- Finding a balance between realism and complexity when composing and fitting a lens model.
+[Tutorial 3: Why Modeling Is Hard](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_2_lens_modeling/tutorial_3_why_modeling_is_hard.ipynb)
+\- Investigate difficult parameter spaces by adjusting priors, simplifying models and searching more thoroughly.
 
-[Tutorial 4: Dealing with Failure](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_2_lens_modeling/tutorial_4_dealing_with_failure.ipynb)
-\- What to do when PyAutoLens finds an inaccurate lens model.
+[Tutorial 4: Linear Profiles](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_2_lens_modeling/tutorial_4_linear_profiles.ipynb)
+\- Solve light-profile intensities with linear algebra and build flexible multi-Gaussian expansions.
 
-[Tutorial 5: Linear Profiles](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_2_lens_modeling/tutorial_5_linear_profiles.ipynb)
-\- Light profiles which capture complex morphologies in a reduced number of non-linear parameters.
+[Tutorial 5: Data and Likelihoods](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_2_lens_modeling/tutorial_5_data_and_likelihoods.ipynb)
+\- Understand how datasets, masks and likelihoods determine which observations constrain the model. Use a positions likelihood penalty to guide lens modeling.
 
-[Tutorial 6: Masking and Positions](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_2_lens_modeling/tutorial_6_masking_and_positions.ipynb)
-\- How to mask and mark positions on your data to improve the lens model.
+[Tutorial 6: Search Chaining](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_2_lens_modeling/tutorial_6_search_chaining.ipynb)
+\- Fit components in stages, using earlier results to fix their geometry in later searches.
 
-[Tutorial 7: Results](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_2_lens_modeling/tutorial_7_results.ipynb)
-\- Overview of the results available after successfully fitting a lens model.
-
-[Tutorial 8: Need for Speed](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_2_lens_modeling/tutorial_8_need_for_speed.ipynb)
-\- How to fit complex models whilst balancing efficiency and run-time.
-
-[Tutorial 9: Search Chaining](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_2_lens_modeling/tutorial_9_search_chaining.ipynb)
-\- Breaking the lens modeling procedure into a chained sequence of model-fits.
-
-[Tutorial 10: Prior Passing](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_2_lens_modeling/tutorial_10_prior_passing.ipynb)
-\- How the results of earlier searches are passed to later searches.
-
-[Tutorial 11: SLaM](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_2_lens_modeling/tutorial_11_slam.ipynb)
-\- Template pipelines for fitting lens models in standardized ways.
+[Tutorial 7: Summary](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_2_lens_modeling/tutorial_7_summary.ipynb)
+\- Review the modeling workflow and choose what to explore next.

docs/howtolens/chapter_3_pixelizations.md

@@ -1,41 +1,23 @@
 # Chapter 3: Pixelizations
 
-In chapter 3, we use **Pixelizations** to reconstruct complex source galaxies on pixelized grids.
+In chapter 3, we reconstruct complex source light on pixelized grids. We use Bayesian evidence to choose the smoothing strength, investigate fits that remain inadequate, and adapt the mesh and regularization to the light distribution.
 
 The chapter contains the following tutorials:
 
-[Tutorial 1: Pixelizations](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_3_pixelizations/tutorial_1_pixelizations.ipynb)
-\- Creating a pixel-grid in the source-plane.
+[Tutorial 1: Pixelizations, Mappers and Inversions](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_3_pixelizations/tutorial_1_pixelizations.ipynb)
+\- Connect mesh points to image pixels and reconstruct complex source light with a linear inversion.
 
-[Tutorial 2: Mappers](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_3_pixelizations/tutorial_2_mappers.ipynb)
-\- How a pixelization maps source-pixels to image-pixels.
+[Tutorial 2: Bayesian Regularization](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_3_pixelizations/tutorial_2_bayesian_regularization.ipynb)
+\- Compare log evidences to choose the regularization strength and examine its dependence on mesh resolution.
 
-[Tutorial 3: Inversions](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_3_pixelizations/tutorial_3_inversions.ipynb)
-\- Inverting the mappings to reconstruct the source's light.
+[Tutorial 3: Borders](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_3_pixelizations/tutorial_3_borders.ipynb)
+\- Explore how masks and border relocation affect the extent and resolution of the source mesh.
 
-[Tutorial 4: Bayesian Regularization](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_3_pixelizations/tutorial_4_bayesian_regularization.ipynb)
-\- Smoothing the source within a Bayesian framework.
+[Tutorial 4: Lens Modeling](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_3_pixelizations/tutorial_4_lens_modeling.ipynb)
+\- Fit lens mass and foreground light alongside a pixelized source, using search chaining and the positions likelihood penalty introduced in chapter 2.
 
-[Tutorial 5: Bayesian Formalism](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_3_pixelizations/tutorial_5_bayesian_formalism.ipynb)
-\- The linear algebra and Bayesian evidence equations behind pixelized source reconstruction.
+[Tutorial 5: Fit Problems](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_3_pixelizations/tutorial_5_fit_problems.ipynb)
+\- See why compact source light challenges mesh resolution and constant regularization, even after choosing the coefficient using evidence.
 
-[Tutorial 6: Borders](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_3_pixelizations/tutorial_6_borders.ipynb)
-\- Preventing highly demagnified image-pixels ruining the inversion.
-
-[Tutorial 7: Lens Modeling](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_3_pixelizations/tutorial_7_lens_modeling.ipynb)
-\- How to use inversions to fit a lens model.
-
-[Tutorial 8: Adaptive Pixelization](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_3_pixelizations/tutorial_8_adaptive_pixelization.ipynb)
-\- A Delaunay mesh which adapts to the mass model's magnification.
-
-[Tutorial 9: Model Fit](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_3_pixelizations/tutorial_9_model_fit.ipynb)
-\- An example lens modeling pipeline which uses an inversion.
-
-[Tutorial 10: Fit Problems](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_3_pixelizations/tutorial_10_fit_problems.ipynb)
-\- The shortcomings of our lens models and inversions.
-
-[Tutorial 11: Brightness Adaption](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_3_pixelizations/tutorial_11_brightness_adaption.ipynb)
-\- Adapting the pixelization to the source's morphology.
-
-[Tutorial 12: Adaptive Regularization](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_3_pixelizations/tutorial_12_adaptive_regularization.ipynb)
-\- Adapting the regularization to the source's morphology.
+[Tutorial 6: Adaptive Reconstruction](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_3_pixelizations/tutorial_6_adaptive_reconstruction.ipynb)
+\- Combine Delaunay meshes, Hilbert brightness adaptation and adaptive Split regularization in a chained lens-model fit.

docs/howtolens/chapter_4_scaling_up_lensing.md

@@ -5,20 +5,20 @@ scaling relations, group and cluster scales, and weak lensing.
 
 The chapter contains the following tutorials:
 
-[Tutorial 1: Extra Galaxies](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_4_scaling_up_lensing/tutorial_1_extra_galaxies.ipynb)
+[Tutorial 1: Extra Galaxies](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_4_scaling_up_lensing/tutorial_1_extra_galaxies.ipynb)
 \- Handling nearby galaxies by scaling their light out of the fit or modeling them explicitly.
 
-[Tutorial 2: Multi Galaxy](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_4_scaling_up_lensing/tutorial_2_multi_galaxy.ipynb)
+[Tutorial 2: Multi Galaxy](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_4_scaling_up_lensing/tutorial_2_multi_galaxy.ipynb)
 \- Modeling lenses with two or more co-dominant lens galaxies and the degeneracies this creates.
 
-[Tutorial 3: Scaling Relation](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_4_scaling_up_lensing/tutorial_3_scaling_relation.ipynb)
+[Tutorial 3: Scaling Relation](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_4_scaling_up_lensing/tutorial_3_scaling_relation.ipynb)
 \- Tying galaxy masses to their luminosities so model complexity stops growing with each galaxy.
 
-[Tutorial 4: Group Scale](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_4_scaling_up_lensing/tutorial_4_group_scale.ipynb)
+[Tutorial 4: Group Scale](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_4_scaling_up_lensing/tutorial_4_group_scale.ipynb)
 \- Modeling group-scale lenses with truncated dPIE members and an optional group dark matter halo.
 
-[Tutorial 5: Cluster Scale](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_4_scaling_up_lensing/tutorial_5_cluster_scale.ipynb)
+[Tutorial 5: Cluster Scale](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_4_scaling_up_lensing/tutorial_5_cluster_scale.ipynb)
 \- Modeling cluster-scale lenses with point-source positions, the CSV interface and multi-plane ray tracing.
 
-[Tutorial 6: Weak Lensing](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_4_scaling_up_lensing/tutorial_6_weak_lensing.ipynb)
+[Tutorial 6: Weak Lensing](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_4_scaling_up_lensing/tutorial_6_weak_lensing.ipynb)
 \- Fitting weak-lensing shear catalogues, which probe mass far beyond the strong lensing region.

docs/howtolens/chapter_optional.md

@@ -1,8 +1,14 @@
-# Chapter: Optional
+# Optional Tutorials
 
-This chapter contains optional tutorials expanding on different aspects of how **PyAutoLens** work.
+These tutorials expand on search choices and runtime after the main modeling chapter. Prior passing is retained as historical background.
 
 The chapter contains the following tutorials:
 
-[Tutorial: Searches](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.11.1.1/notebooks/chapter_optional/tutorial_searches.ipynb)
-\- Alternative non-linear searches to sample parameter space.
+[Tutorial: Alternative Searches](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_optional/tutorial_searches.ipynb)
+\- Explore alternative search settings, optimisation and Markov chain Monte Carlo.
+
+[Tutorial: Need for Speed](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_optional/tutorial_need_for_speed.ipynb)
+\- Understand search effort, likelihood cost, JAX compilation, batching and hardware when assessing runtime.
+
+[Historical Tutorial: Prior Passing](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/main/notebooks/chapter_optional/tutorial_prior_passing.ipynb)
+\- Read about older workflows that narrowed priors between searches. For the recommended component-separation approach, follow chapter 2 tutorial 6.

docs/howtolens/howtolens.md

@@ -6,15 +6,21 @@ The best way to learn **PyAutoLens** is by going through the **HowToLens** lectu
 repository at [PyAutoLabs/HowToLens](https://github.com/PyAutoLabs/HowToLens).
 
 The lectures are provided as Jupyter notebooks (and Python scripts), and they are linked to via this readthedocs. The
-lectures are composed of four chapters
+lectures are composed of four chapters:
 
 - **Introduction** - An introduction to strong gravitational lensing and **PyAutolens**.
 - **Lens Modeling** - How to model strong lenses, including a primer on Bayesian non-linear analysis and
   non-linear search chaining.
-- **Pixelizations** - How to perform pixelized reconstructions of the source-galaxy.
+- **Pixelizations** - Reconstruct complex source light, choose regularization using Bayesian evidence,
+  diagnose fit problems and adapt the mesh and smoothing to the light distribution.
 - **Scaling Up Lensing** - Extra galaxies, multi-galaxy lenses, scaling relations, group and cluster
   scales, and weak lensing.
 
+Optional tutorials cover alternative searches and runtime, with prior passing retained as historical background.
+
+The tutorial links open the current course on `main`. For the notebooks associated with a particular release,
+select that release tag in the [HowToLens repository](https://github.com/PyAutoLabs/HowToLens/tags).
+
 ## How to Tackle HowToLens
 
 The HowToLens lecture series currently sits at 4 chapters, and each will take around 3-6 hours to go through thoroughly.
@@ -52,7 +58,7 @@ Notebooks are a different way to write, view and use Python code. Compared to th
 - Images and visualization from a code to be displayed directly underneath it.
 - Text script to appear between the blocks of code.
 
-This makes them an ideal way for us to present the HowToFit lecture series, therefore I recommend you get yourself
+This makes them an ideal way for us to present the HowToLens lecture series, therefore I recommend you get yourself
 a Jupyter notebook viewer (<https://jupyter.org/>) if you haven't done so already.
 
 If you *really* want to use Python scripts, all tutorials are also supplied as `.py` files in the `scripts` folder