docs: three-ways-to-learn guide + prune stale API-doc references (#593)

Phase C: add a 'Three Ways to Learn PyAutoLens' subsection (manual
navigation / AI chat assistant / fully agentic AI) to the new-user guide
and README; reframe autolens_assistant from experimental to a first-class
option in README + docs/index.

Phase A: prune docs/api/*.rst references to removed API — the OO plotting
subsystem (MatPlot2D/Cmap/*Scatter, replaced by the functional plot API),
PySwarms searches, PointDict, SetupAdapt->AdaptImages, OverSampling->
OverSampler, and dead linear Chameleon entries. Re-audit clean.

Issue #592.

Co-authored-by: Jammy2211 <JNightingale2211@gmail.com>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

README.md

@@ -23,7 +23,7 @@ When two or more galaxies are aligned perfectly down our line-of-sight, the back
 
 This is called strong gravitational lensing and **PyAutoLens** makes it **simple** to model strong gravitational lenses, using JAX to **accelerate lens modeling on GPUs**.
 
-> 🤖 **Prototype:** [**autolens_assistant**](https://github.com/PyAutoLabs/autolens_assistant) is an early-stage AI assistant you talk to in natural language to do lens modeling end-to-end. It is experimental and **not the recommended starting point** — the readthedocs, autolens_workspace, and HowToLens below remain the canonical entry points. Try it if you'd like to drive PyAutoLens by conversation.
+> 🤖 **AI-assisted use:** you can also learn and drive **PyAutoLens** with AI — either a browser chat assistant (ChatGPT, Claude) pointed at [**autolens_assistant**](https://github.com/PyAutoLabs/autolens_assistant), or a fully agentic coding tool (Claude Code, Codex) that runs lens modeling end-to-end on your machine. See the **Three Ways to Learn PyAutoLens** section below.
 
 ## Getting Started
 
@@ -34,6 +34,16 @@ The following links are useful for new starters:
 - [The autolens_workspace GitHub repository](https://github.com/PyAutoLabs/autolens_workspace): example scripts covering every **PyAutoLens** use case.
 - [The HowToLens GitHub repository](https://github.com/PyAutoLabs/HowToLens): a Jupyter notebook lecture series teaching strong lensing and lens modeling from the ground up.
 
+## Three Ways to Learn PyAutoLens
+
+There are three ways to learn how to use **PyAutoLens**, which you can freely mix and match:
+
+1. **Manual navigation** — read the workspace guides yourself, starting from the [new user guide](https://pyautolens.readthedocs.io/en/latest/overview/overview_2_new_user_guide.html) and the `start_here` notebooks, which are organised by lens scale and dataset type.
+2. **AI chat assistant** — ask questions to a conversational AI assistant such as ChatGPT or Claude in the browser. Point it at the [autolens_assistant](https://github.com/PyAutoLabs/autolens_assistant) repository and ask a question like *"How do I model a galaxy-scale strong lens observed with Hubble imaging?"*.
+3. **Fully agentic AI** — drive **PyAutoLens** end-to-end with an agentic coding tool such as [Claude Code](https://claude.com/claude-code) or [Codex](https://developers.openai.com/codex) together with [autolens_assistant](https://github.com/PyAutoLabs/autolens_assistant). These can inspect your data, write and run scripts, and manage a lens-modeling project directly on your machine.
+
+See [autolens_assistant](https://github.com/PyAutoLabs/autolens_assistant) for more on the AI-assisted options (2 and 3).
+
 ## Community & Support
 
 Support for **PyAutoLens** is available via our Slack workspace, where the community shares updates, discusses

docs/api/data.rst

@@ -35,7 +35,6 @@ For datasets taken with a CCD (or similar imaging device), including objects whi
    Imaging
    SimulatorImaging
    Convolver
-   Convolver
 
 
 Interferometer
@@ -67,7 +66,7 @@ applied to datasets to apply over sampling to their fit.
    :template: custom-class-template.rst
    :recursive:
 
-   OverSampling
+   OverSampler
 
 
 1D Data Structures

docs/api/mass.rst

@@ -187,5 +187,3 @@ inversion during each likelihood evaluation rather than as a free non-linear par
    ExponentialGradientSph
    DevVaucouleurs
    DevVaucouleursSph
-   Chameleon
-   ChameleonSph

docs/api/modeling.rst

@@ -39,8 +39,6 @@ Markov Chain Monte Carlo (MCMC) and Maximum Likelihood Estimaotrs (MLE).
    BFGS
    DynestyDynamic
    Emcee
-   PySwarmsLocal
-   PySwarmsGlobal
 
 Priors
 ------
@@ -65,4 +63,4 @@ Adapt
 .. autosummary::
    :toctree: generated/
 
-   SetupAdapt
+   AdaptImages

docs/api/plot.rst

@@ -97,83 +97,3 @@ Module-level functions for visualizing non-linear search results.
    corner_anesthetic
    subplot_parameters
    log_likelihood_vs_iteration
-
-Plot Customization [aplt]
--------------------------
-
-Customize figures created via ``Plotter`` objects, including changing ``matplotlib`` settings and adding
-visuals to figures.
-
-.. currentmodule:: autogalaxy.plot
-
-.. autosummary::
-   :toctree: _autosummary
-   :template: custom-class-template.rst
-   :recursive:
-
-   MatPlot1D
-   MatPlot2D
-   Visuals1D
-   Visuals2D
-
-Matplot Lib Wrappers [aplt]
----------------------------
-
-Wrappers for every ``matplotlib`` function used by a ``Plotter``, allowing for detailed customization of
-every figure and subplot.
-
-.. currentmodule:: autogalaxy.plot
-
-**Matplotlib Wrapper Base Objects:**
-
-.. autosummary::
-   :toctree: _autosummary
-   :template: custom-class-template.rst
-   :recursive:
-
-   Units
-   Figure
-   Axis
-   Cmap
-   Colorbar
-   ColorbarTickParams
-   TickParams
-   YTicks
-   XTicks
-   Title
-   YLabel
-   XLabel
-   Legend
-   Output
-
-**Matplotlib Wrapper 1D Objects:**
-
-.. autosummary::
-   :toctree: _autosummary
-   :template: custom-class-template.rst
-   :recursive:
-
-   YXPlot
-
-**Matplotlib Wrapper 2D Objects:**
-
-.. autosummary::
-   :toctree: _autosummary
-   :template: custom-class-template.rst
-   :recursive:
-
-   ArrayOverlay
-   GridScatter
-   GridPlot
-   VectorYXQuiver
-   PatchOverlay
-   VoronoiDrawer
-   OriginScatter
-   MaskScatter
-   BorderScatter
-   PositionsScatter
-   IndexScatter
-   MeshGridScatter
-   ParallelOverscanPlot
-   SerialPrescanPlot
-   SerialOverscanPlot

docs/api/point.rst

@@ -20,7 +20,6 @@ named point sources.
    :recursive:
 
    PointDataset
-   PointDict
 
 Solver
 ------

docs/index.md

@@ -9,7 +9,7 @@ When two or more galaxies are aligned perfectly down our line-of-sight, the back
 This is called strong gravitational lensing and **PyAutoLens** makes it simple to model strong gravitational lenses, using JAX to **accelerate lens modeling on GPUs**.
 
 ```{note}
-🤖 **Prototype:** [autolens_assistant](https://github.com/PyAutoLabs/autolens_assistant) is an early-stage AI assistant you talk to in natural language to do lens modeling end-to-end. It is experimental and **not the recommended starting point** — the readthedocs, autolens_workspace, and HowToLens below remain the canonical entry points. Try it if you'd like to drive PyAutoLens by conversation.
+🤖 **AI-assisted use:** alongside reading the guides, you can learn and drive **PyAutoLens** with AI — either a browser chat assistant (ChatGPT, Claude) pointed at [autolens_assistant](https://github.com/PyAutoLabs/autolens_assistant), or a fully agentic coding tool (Claude Code, Codex) that runs lens modeling end-to-end on your machine. The [new user guide](https://pyautolens.readthedocs.io/en/latest/overview/overview_2_new_user_guide.html) describes all three ways to learn.
 ```
 
 # Getting Started

docs/overview/overview_2_new_user_guide.md

@@ -6,7 +6,27 @@
 different types of data (e.g. imaging, interferometer, and point-source observations). Depending on the scientific questions you are interested in, the analysis you perform may differ significantly.
 
 The autolens_workspace contains a suite of example Jupyter Notebooks, organised by lens scale and dataset type.
-To help you find the most appropriate starting point, we begin by answering two simple questions.
+
+## Three Ways To Learn PyAutoLens
+
+There are three ways to learn how to use **PyAutoLens**, which you are free to mix and match:
+
+1. **Manual Navigation**: Read the workspace guides yourself. To find the example notebook best suited to your
+   science case, work through the two questions below ("What Scale Lens?" and "What Dataset Type?"), which point you
+   to the right starting point. This is the traditional route, and the rest of this guide supports it.
+
+2. **AI Chat Assistant**: Ask questions to a conversational AI assistant such as ChatGPT or Claude in the browser.
+   Point it at the [autolens_assistant](https://github.com/PyAutoLabs/autolens_assistant) repository and ask questions
+   like *"How do I model a galaxy-scale strong lens observed with Hubble imaging?"*. This is ideal for learning the API,
+   working out how to perform a calculation, and interpreting or debugging errors.
+
+3. **Fully Agentic AI**: Use an agentic coding tool such as [Claude Code](https://claude.com/claude-code) or
+   [Codex](https://developers.openai.com/codex) together with [autolens_assistant](https://github.com/PyAutoLabs/autolens_assistant).
+   These can inspect your data, write and run scripts, and manage an end-to-end lens modeling project directly on your
+   machine. See the [autolens_assistant](https://github.com/PyAutoLabs/autolens_assistant) repository for more information.
+
+The rest of this guide supports **manual navigation**: we begin by answering two simple questions to find your most
+appropriate starting point.
 
 ## What Scale Lens?