Merge pull request #654 from PyAutoLabs/claude/pyautolens-doc-reorganization-w6a1l5

docs: RTD three-regime remainder — api regime notes, cookbook recipes, flagships

Author: Jammy2211

docs/api/galaxy.rst

@@ -33,4 +33,20 @@ The ``Redshift`` object does not need to be used for general **PyAutoGalaxy** us
    :template: custom-class-template.rst
    :recursive:
 
-    Redshift
+    Redshift
+
+Galaxy Catalogues (CSV)
+-----------------------
+
+Load many galaxies from a ``y, x, luminosity`` CSV catalogue — the input format of the
+scaling-relation galaxy tier used at multi-galaxy, group and cluster scale (see the
+``multi_galaxy``, ``group`` and ``cluster`` packages of the ``autolens_workspace``).
+``galaxy_table_from_csv`` reads the catalogue; the two ``*_from_csv_tables`` functions
+build instances or model components from it.
+
+.. autosummary::
+   :toctree: _autosummary
+
+   galaxy_table_from_csv
+   galaxies_from_csv_tables
+   galaxy_af_models_from_csv_tables

docs/api/mass.rst

@@ -5,6 +5,13 @@ Mass Profiles
 Total [ag.mp]
 -------------
 
+The ``Isothermal`` / ``PowerLaw`` family are the standard **untruncated** profiles for
+galaxy-scale and multi-galaxy lenses (no host halo, so no tidal truncation). The ``dPIE``
+family are **tidally truncated** profiles for the member galaxies of group- and
+cluster-scale lenses, whose ``r_cut`` encodes stripping by the host halo's potential
+(``dPIEMass`` is parameterized by Lenstool's native ``sigma`` — the fiducial dispersion
+sigma_LT; ``dPIEMassB0`` by the deflection normalization ``b0``).
+
 .. currentmodule:: autogalaxy.profiles.mass
 
 .. autosummary::

docs/api/point.rst

@@ -6,6 +6,10 @@ Point sources arise when the background object is compact (e.g. a quasar, supern
 compact radio source) and is modelled by its image-plane positions, flux ratios, and/or
 time delays rather than by a resolved surface-brightness distribution.
 
+They are also the standard source strategy of **cluster-scale** lens modeling, where each
+of many background sources contributes its multiple-image positions (each at its own
+redshift, ray-traced multi-plane) — see the ``cluster`` package of the ``autolens_workspace``.
+
 Dataset
 -------
 

docs/general/model_cookbook.md

@@ -365,6 +365,52 @@ as manually customize it in the .json file directory.
 
 This is used for composing complex models of group scale lenses.
 
+## Multi Galaxy, Group and Cluster Models
+
+Above galaxy scale, models are composed for three regimes (see the New User Guide's "What Scale
+System?" ladder — all groups and clusters are multi-galaxy systems, but not vice versa):
+
+**Multi-galaxy lenses** (2+ co-dominant deflectors, no host halo): one free light + mass model per
+deflector, composed in a loop with **untruncated** isothermals (no host halo means no tidal
+truncation):
+
+```python
+lens_dict = {}
+
+for i, centre in enumerate(main_lens_centres):
+    mass = af.Model(al.mp.Isothermal)
+    mass.centre = (centre[0], centre[1])
+
+    lens_dict[f"lens_{i}"] = af.Model(al.Galaxy, redshift=0.5, mass=mass)
+
+model = af.Collection(galaxies=af.Collection(**lens_dict, source=source))
+```
+
+**Group-scale lenses** add two things as explicit modelling choices: an optional dark-matter
+**group halo**, and faint members whose masses are tied to their luminosities through a shared
+scaling relation, so N galaxies cost one free parameter (composed via prior arithmetic on a
+shared prior):
+
+```python
+einstein_radius_ref = af.UniformPrior(lower_limit=0.0, upper_limit=1.0)
+
+for i, (centre, luminosity) in enumerate(zip(centres, luminosities)):
+    mass = af.Model(al.mp.IsothermalSph)
+    mass.centre = (centre[0], centre[1])
+    mass.einstein_radius = einstein_radius_ref * (luminosity / reference_luminosity) ** 0.5
+```
+
+**Cluster-scale lenses** keep the group mass framework (halo + tidally truncated ``dPIE``
+members on scaling relations) but change the source strategy: many point-source multiple-image
+position datasets, each at its own redshift, fitted via ``AnalysisPoint``.
+
+The following example notebooks show each regime's full model composition:
+
+<https://github.com/PyAutoLabs/autolens_workspace/blob/main/notebooks/multi_galaxy/modeling.ipynb>
+<https://github.com/PyAutoLabs/autolens_workspace/blob/main/notebooks/group/start_here.ipynb>
+<https://github.com/PyAutoLabs/autolens_workspace/blob/main/notebooks/group/features/group_halo/modeling.ipynb>
+<https://github.com/PyAutoLabs/autolens_workspace/blob/main/notebooks/cluster/start_here.ipynb>
+
 ## Many Profile Models (Advanced)
 
 Features such as the Multi Gaussian Expansion (MGE) and shapelets compose models consisting of 50 - 500+ light

docs/overview/overview_1_start_here.md

@@ -352,8 +352,8 @@ progressively improving the quality of the fit until the model closely reproduce
 
 **Credit: Amy Etherington**
 
-The next documentation page guides you through lens modeling for a variety of lensing regimes (e.g. galaxy–galaxy lenses,
-cluster-scale lenses) and data types (e.g. CCD imaging, interferometer data).
+The next documentation page guides you through lens modeling for a variety of lensing regimes (galaxy-scale,
+multi-galaxy, group-scale and cluster-scale lenses) and data types (e.g. CCD imaging, interferometer data).
 
 ## Simulations
 
@@ -364,15 +364,16 @@ Simulating strong lenses is often essential, for example to:
 - Test lensing theory in a fully controlled environment.
 
 The next documentation page guides you through how to simulate lenses for different types of strong
-lenses (e.g. galaxy–galaxy lenses, cluster-scale lenses) and different types of data (e.g. CCD imaging, interferometer data).
+lenses (galaxy-scale, multi-galaxy, group-scale and cluster-scale) and different types of data (e.g. CCD imaging,
+interferometer data).
 
 ## Wrap Up
 
 This completes the introduction to **PyAutoLens**, including a brief overview of the core API for lensing calculations,
 lens modeling, and data simulation.
 
-Different users will be interested in strong lenses across different lensing regimes (e.g. galaxy-scale or
-cluster-scale lenses) and using different data types (e.g. CCD imaging or interferometer data).
+Different users will be interested in strong lenses across different lensing regimes (galaxy-scale, multi-galaxy,
+group-scale or cluster-scale lenses) and using different data types (e.g. CCD imaging or interferometer data).
 
 The autolens_workspace repository contains a wide range of examples and tutorials covering these use cases. The
 next documentation page helps new users identify the most appropriate starting point based on their scientific goals.

docs/overview/overview_2_new_user_guide.md

@@ -39,6 +39,12 @@ but not vice versa. What changes as you climb is first the mass model, then the
   reconstructing extended sources, and the lens galaxies' light is not modeled. If you are interested in clusters, go
   to the [cluster/start_here.ipynb](https://github.com/PyAutoLabs/autolens_workspace/blob/main/notebooks/cluster/start_here.ipynb) notebook.
 
+For a sense of the real science each rung anchors to: multi-galaxy lenses include merging-pair systems like
+SDSS J1011+0143 (two SIEs + shear; Shu et al. 2016) and the famous time-delay lens B1608+656; group-scale
+lenses include CSWA 19 (Ding et al. 2025, modeled with **PyAutoLens**) and the SL2S group sample; cluster-scale
+lenses include the Hubble Frontier Fields clusters, most notably Abell 2744 (Bergamini et al. 2023) — the
+system the workspace's cluster `start_here` models.
+
 ## What Dataset Type?
 
 If you are interested in galaxy-scale strong lenses, you now need to decide what type of strong lens data you are