docs: plan the multi_galaxy/group/cluster lensing-regime split (epic + 9 child prompts)

draft/docs/autolens/docs_three_regime_restructure.md

@@ -0,0 +1,63 @@
+# PyAutoLens RTD docs: three-regime restructure (multi_galaxy / group / cluster)
+
+Type: docs
+Target: PyAutoLens
+Repos:
+- PyAutoLens
+Difficulty: medium
+Autonomy: supervised
+Priority: high
+Status: draft
+Parent: draft/docs/autolens/split_lensing_regimes.md
+
+Restructure the PyAutoLens Sphinx/RTD documentation (`PyAutoLens/docs/`) around
+the three above-galaxy-scale regimes defined in the parent plan: `multi_galaxy`,
+`group`, `cluster` — each presented as its own section with its own tutorials,
+example links, API pointers and modelling philosophy.
+
+## Landed (2026-07-25, this task branch)
+
+- `docs/overview/overview_2_new_user_guide.md`: the multi_galaxy rung and the
+  four-step ladder routing with the analysis-split prose landed (PyAutoLens
+  `c086863` + review fixes). The remaining items below are still open.
+
+## Changes
+
+- ~~`docs/overview/overview_2_new_user_guide.md`~~ LANDED (see above). For
+  reference, the rung decision rules used:
+  - multi_galaxy: ≥2 co-dominant deflectors, no host halo, standard extended
+    source.
+  - group: optional host halo (explicit modelling choice), truncated members
+    on scaling relations, one dominant extended source.
+  - cluster: same mass framework as group; many sources at many redshifts →
+    point-source/multi-image-position workflow by default.
+  Include the taxonomy sentence: all groups and clusters are multi-galaxy
+  systems, but not vice versa.
+- `docs/overview/overview_1_start_here.md` + `overview_3_features.md`: add the
+  regime split where scales are enumerated; link the three start_here Colab
+  notebooks.
+- `docs/api/`: ensure the mass/galaxy/point API pages surface the
+  regime-relevant surfaces where users will look for them — dPIE profiles,
+  `al.sr` scaling relations, `galaxy_table_from_csv` /
+  `galaxies_from_csv_tables` / `galaxy_models_from_csv` CSV APIs, and the
+  point-source/`PointSolver` machinery — grouped or cross-referenced by
+  regime (a short "which regime uses this" note per surface is enough; do not
+  fork the API reference into three copies).
+- `docs/general/model_cookbook.md`: add multi_galaxy, group (both
+  with/without-halo compositions) and cluster model recipes.
+- Scientific grounding: each regime section cites 2–3 flagship
+  systems/surveys from the parent plan's literature research (e.g. the
+  multi_galaxy flagship, SL2S/CASSOWARY groups, HFF/A2744 clusters) so the
+  docs point at real, recognisable science.
+
+## Ordering
+
+Land after (or alongside) the `multi_galaxy` workspace package so notebook
+links resolve; the group/cluster narrative edits can reference the workspace
+tasks' outcomes but must not block on them.
+
+## Acceptance
+
+- Sphinx build clean against `sphinx_warning_baseline.txt`.
+- Every notebook link resolves to an existing notebook on the release branch
+  convention used by the docs.

draft/docs/autolens/multi_galaxy_package.md

@@ -0,0 +1,108 @@
+# multi_galaxy package: new regime package in autolens_workspace
+
+Type: docs
+Target: autolens_workspace
+Repos:
+- autolens_workspace
+- autolens_workspace_test
+Difficulty: large
+Autonomy: supervised
+Priority: high
+Status: in progress — core landed on branch claude/pyautolens-doc-reorganization-w6a1l5 (2026-07-25)
+Parent: draft/docs/autolens/split_lensing_regimes.md
+
+## Landed (2026-07-25, this task branch)
+
+- autolens_workspace: scripts/multi_galaxy/ with start_here.py, simulator.py
+  (J1011+0143-like merging pair — 0.9" separation, ~1.8" Einstein cross
+  verified with 4 bright images + central image), modeling.py,
+  README.md (regime-ladder + analysis-split table), features/README.md;
+  top-level README ladder section; group/cluster README + start_here
+  pointers; smoke registration (both fit scripts validated green under
+  PYAUTO_TEST_MODE=2 from a clean slate); notebooks + navigator regenerated.
+- autolens_workspace_test: scripts/multi_galaxy/model_fit.py (end-to-end,
+  structural assertions locking the regime) + imaging/multi_galaxy_mge.py
+  relocated to multi_galaxy/composition_mge.py; smoke updated; validated.
+- PyAutoLens docs: New User Guide four-rung ladder + multi_galaxy links
+  (full RTD restructure remains with docs_three_regime_restructure.md).
+
+## Remaining
+
+- features/ scripts (extra_galaxies, scaling_galaxies with untruncated
+  isothermals, pixelization) — currently README cross-links only.
+- Swap start_here to the REAL SDSS J1011+0143 HST data (F555W/F814W via
+  MAST) once frames are prepared; the simulated look-alike is the interim.
+- likelihood_function.py / fit.py mirrors of the group package equivalents.
+- autolens_workspace_test multi_galaxy/jax_likelihood/ variant (only
+  model_fit + the relocated composition test landed).
+
+Create the new `scripts/multi_galaxy/` package in @autolens_workspace — the first
+of the three above-galaxy-scale regimes (see the parent plan for the full design
+and literature research). The name is **`multi_galaxy`**, NOT `multi_galaxy_lens`
+— concise, and mirrors the `multi_galaxy` package planned for
+@autogalaxy_workspace. No collision with the existing `multi/` package (which is
+multi-*dataset*/wavelength and keeps its name).
+
+## Regime definition (from the parent plan)
+
+Galaxy-scale strong lenses where two or more galaxies contribute significantly
+(co-dominantly) to the lensing potential, with NO dominant group/cluster dark
+matter halo. Individual halos ~10^11–10^13 M_sun. Mass model = one EPL/SIE per
+significant deflector + external shear where appropriate; deflectors are
+co-dominant lenses, not satellites in a host halo. Source modelling is the
+standard extended-source workflow (parametric Sersic/MGE or pixelized
+Delaunay/adaptive meshes) — unchanged from `imaging/`.
+
+Taxonomy note for all narrative prose: all group- and cluster-scale lenses are
+multi-galaxy systems, but not vice versa. `multi_galaxy` is the base rung of the
+three-regime ladder; group adds the (optional) host halo + truncated members;
+cluster keeps that mass framework and changes the source strategy.
+
+## Contents
+
+- `start_here.py` — modeled on `group/start_here.py`'s structure (JAX section,
+  Colab setup, centre-input JSON/GUI, live visual update). Two co-dominant lens
+  galaxies, one extended source, standard `AnalysisImaging` fit. Use REAL data:
+  **SDSS J1011+0143** (arXiv:1602.02927, Shu et al. 2016) — a merging PAIR of
+  lens galaxies (~4.2 kpc separation, z=0.331) lensing a z=2.701 Lya emitter
+  into a theta_E ~ 1.84" cross/arc; published model is exactly two SIEs +
+  shear; public archival HST F555W/F814W via MAST (pin down the program ID at
+  implementation time; simulate a look-alike if the frames prove unsuitable).
+  Science hook for the prose: the ~1.7 kpc mass/light offsets a single-SIE
+  model cannot produce. Runner-up if J1011+0143 falls through: B1608+656
+  (see plan — advanced-example caveats).
+- `simulator.py` — simulate a two/three-deflector lens (also used to generate
+  the bundled example dataset if real data cannot be redistributed).
+- `modeling.py` — detailed modeling walkthrough (compose N main galaxies,
+  centres from JSON, priors, MGE lens light per galaxy).
+- `likelihood_function.py`, `fit.py` — mirror the group package equivalents.
+- `features/` — extra_galaxies and scaling_galaxies as EXTENSIONS (not in the
+  default model), plus pixelization, MGE, no_lens_light, following
+  `group/features/` layout. Scaling galaxies here use UNTRUNCATED isothermals
+  (no dPIE/truncation — truncation is physically motivated by a host halo's
+  tidal field, which this regime lacks) and the prose must say that at this
+  scale scaling galaxies are just "a load of galaxies far from the lens".
+- `README.md` — regime definition, file inventory, pointers up the ladder to
+  `group/` and `cluster/`.
+
+## Cross-cutting edits (same PR)
+
+- Top-level `autolens_workspace` `README.md`, root `start_here.py` and any
+  "which regime am I?" prose: introduce the three-regime ladder and link
+  `multi_galaxy/start_here.ipynb`.
+- `group/README.md` + `group/start_here.py` opening prose: point down to
+  `multi_galaxy/` for systems without a host halo (currently they point only
+  to `imaging/` and up to `cluster/`).
+- `smoke_tests.txt` + `config/build/profile_smoke.yaml`: register the new
+  scripts; regenerate notebooks + navigator catalogue via PyAutoHands.
+
+## autolens_workspace_test (same-named branch, second PR)
+
+Mirror the taxonomy: add `scripts/multi_galaxy/` integration tests (model_fit +
+jax_likelihood variant) following the existing per-dataset subfolder pattern.
+
+## Acceptance
+
+- `python .github/scripts/run_smoke.py` green with the new entries.
+- Notebooks + navigator catalogue regenerated.
+- No use of the string `multi_galaxy_lens` anywhere.