feat: add LLM catalogue layer (HowToGalaxy is now talkable)

.github/workflows/navigator_check.yml

@@ -0,0 +1,17 @@
+name: Navigator Check
+
+# Thin caller for PyAutoBuild's reusable navigator-catalogue check. The check
+# logic (path/banner lint + catalogue staleness) and its entrypoints live in
+# PyAutoBuild/autobuild; this repo only declares which generator project to run.
+# See PyAutoLabs/PyAutoBuild/.github/workflows/navigator_check.yml.
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  navigator:
+    uses: PyAutoLabs/PyAutoBuild/.github/workflows/navigator_check.yml@main
+    with:
+      project: howtogalaxy

.navigator_check_ignore

@@ -0,0 +1,9 @@
+# Paths exempt from the navigator path/banner checks (see
+# PyAutoBuild/autobuild/check_navigator.py). One path or glob per line.
+#
+# CLAUDE.md's "Relationship to autogalaxy_workspace" section mentions sibling
+# autogalaxy_workspace scripts in prose (as the next destination after a concept).
+# Those paths live in the separate autogalaxy_workspace repo, not here, so the
+# path-existence check would flag them as missing. Exempt them.
+scripts/imaging/modeling.py
+scripts/guides/

llms-full.txt

@@ -0,0 +1,76 @@
+AUTO-GENERATED by PyAutoBuild — do not edit by hand; regenerate with generate.py.
+
+# HowToGalaxy Lectures — Full Catalogue
+
+> Complete, generated listing of every script (and its matching notebook) in this
+> workspace, grouped by top-level `scripts/` folder. This is the expanded companion to
+> the curated `llms.txt` routing layer. Each entry links the script's title to its path
+> and gives the first line of its docstring; `Contents:` lists the sections within.
+
+## chapter_1_introduction
+
+- [Tutorial 0: Visualization](scripts/chapter_1_introduction/tutorial_0_visualization.py): In this tutorial, we quickly cover visualization in **PyAutoGalaxy** and make sure images display clearly in your Jupyter notebook and on your computer screen.
+  - Contents: Directories, Dataset, Plot Customization, Subplots, Visuals, Wrap Up
+- [HowToGalaxy: Introduction](scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py): Nearly a century ago, Edwin Hubble famously classified galaxies into three distinct groups: ellipticals, spirals and irregulars. He produced a diagram of these galaxies, called the Hubble Tuning Fork, which is shown below and still discussed by astronomers in the modern day:
+  - Contents: Grids, Geometry, Light Profiles, Galaxies, One Dimension Projection, Unit Conversion, Wrap Up
+- [Tutorial 2: Data](scripts/chapter_1_introduction/tutorial_2_data.py): In the previous tutorial, we used light profiles to create images of galaxies. However, those images don't accurately represent what we would observe through a telescope.
+  - Contents: Initial Setup, Optics Blurring, Poisson Noise, Background Sky, Simulator, Output, Wrap Up
+- [Tutorial 3: Fitting](scripts/chapter_1_introduction/tutorial_3_fitting.py): In previous tutorials, we used light profiles to create simulated images of galaxies and visualized how these images would appear when captured by a CCD detector on a telescope like the Hubble Space Telescope.
+  - Contents: Dataset, Mask, Masked Grid, Fitting, Incorrect Fit, Model Fitting, Wrap Up
+- [tutorial_4_methods](scripts/chapter_1_introduction/tutorial_4_methods.py): (no summary in script docstring)
+- [Tutorial 9: Summary](scripts/chapter_1_introduction/tutorial_5_summary.py): In this chapter, we have learnt that:
+  - Contents: Initial Setup, Object Composition, Visualization, Code Design, Source Code, Wrap Up
+
+## chapter_2_modeling
+
+- [Tutorial 1: Non-linear Search](scripts/chapter_2_modeling/tutorial_1_non_linear_search.py): The starting point for most scientific analysis conducted by an Astronomer is that they have observations of a galaxy using a telescope like the Hubble Space Telescope, and seek to learn about the galaxy and the Universe from these observations. With **PyAutoGalaxy**, we seek to learn about the galaxy's structure and morphology, asking questions like how big is the galaxy, is it disky or bulgy, and how is its light distributed?
+  - Contents: Parameter Space, Non-Linear Search, Search Types, Deeper Background, Data, Model, Priors, Analysis, Searches, Maximum Likelihood Estimation (MLE), Markov Chain Monte Carlo (MCMC), Nested Sampling, Result, Samples, Customizing Searches, Wrap Up
+- [Tutorial 2: Practicalities](scripts/chapter_2_modeling/tutorial_2_practicalities.py): In the last tutorial, we introduced foundational statistical concepts essential for model-fitting, such as parameter spaces, likelihoods, priors, and non-linear searches. Understanding these statistical concepts is crucial for performing model fits effectively.
+- [Tutorial 3: Realism and Complexity](scripts/chapter_2_modeling/tutorial_3_realism_and_complexity.py): In the previous two tutorials, we fitted a fairly basic model: the galaxy's light was a single bulge component. In real observations we know that galaxies are observed to have multiple different morphological structures.
+  - Contents: Initial Setup, Model + Search + Analysis, Result, Global and Local Maxima, Wrap Up
+- [Tutorial 4: Dealing With Failure](scripts/chapter_2_modeling/tutorial_4_dealing_with_failure.py): In the previous tutorial we intentionally made our non-linear search infer a local maxima solution and therefore return a physically incorrect model. In this tutorial, we will pretend that we have modeled our galaxy and inferred a local maxima. We introduce three approaches one can take that changes how we fit the model, all of which have the aim of ensuring we infer the global maxima:
+  - Contents: Initial Setup, Approach 1: Prior Tuning, Approach 2: Reducing Complexity, Approach 3: Look Harder
+- [Tutorial 5: Linear Profiles](scripts/chapter_2_modeling/tutorial_5_linear_profiles.py): In the previous tutorial we learned how to balance model complexity with our non-linear search in order to infer accurate model solutions and avoid failure. We saw how in order to fit a model accurately one may have to parameterize and fit a simpler model with fewer non-linear parameters, at the expense of fitting the data less accurately.
+  - Contents: Initial Setup, Linear Light Profiles, Run Time, Result, Intensities, Visualization, Basis, Model Fit, Disk MGE, Multi Gaussian Expansion Benefits, Positive Only Solver, Other Basis Functions, Wrap Up
+- [Tutorial 6: Masking](scripts/chapter_2_modeling/tutorial_6_masking.py): We have learnt everything we need to know about non-linear searches to model a galaxy and infer a good lens model solution. Now, lets consider masking in more detail, something we have not given much consideration previously. We'll also learn a neat trick to improve the speed and accuracy of a non-linear search.
+  - Contents: Initial Setup, Mask, Model + Search + Analysis, Discussion, Wrap Up
+- [Tutorial 5: Results](scripts/chapter_2_modeling/tutorial_7_results.py): In the previous tutorials, each search returned a `Result` object, which we used to plot the maximum log likelihood fit each model-fit. In this tutorial, we'll take a look at the result object in a little more detail.
+  - Contents: Initial Setup, Galaxies & Fit, Samples, Workspace, Database, Wrap Up
+- [Tutorial 8: Need For Speed](scripts/chapter_2_modeling/tutorial_8_need_for_speed.py): In this chapter, we have learnt how to model galaxies and how to balance complexity and realism to ensure that we infer a good model.
+  - Contents: Searching Non-linear Parameter Space, Algorithmic Optimization, Data Quantity, Wrap Up
+
+## chapter_3_search_chaining
+
+- [Tutorial 1: Search Chaining](scripts/chapter_3_search_chaining/tutorial_1_search_chaining.py): In chapter 2, we learnt how to perform modeling using a non-linear search. In all of the tutorials, we fitted the data using just one non-linear search. In this chapter, we introduce a technique called 'non-linear search chaining', which fits a model using a sequence of non-linear searches. The initial searches fit simpler models whose parameter spaces can be more accurately and efficiently sampled. The results of this search are then passed to later searches which fit models of gradually increasing complexity.
+  - Contents: Initial Setup, Model, Search + Analysis, Result, Prior Passing, Result, Wrap Up
+- [Tutorial 2: Prior Passing](scripts/chapter_3_search_chaining/tutorial_2_prior_passing.py): In the previous tutorial, we used non-linear search chaining to break the model-fitting procedure down into two non-linear searches. This used an initial search to fit a simple model, whose results were used to tune and initialize the priors of a more complex model that was fitted by the second search.
+  - Contents: Initial Setup, Model, Search, Result (Search 1), Prior Passing, Result, Wrap Up, Detailed Explanation Of Prior Passing, EXAMPLE
+- [Tutorial 3: Two Galaxies](scripts/chapter_3_search_chaining/tutorial_3_x2_galaxies.py): Up to now, all the images we've fitted had one galaxy. However, we saw in chapter 1 that our galaxies object can consist of multiple galaxies which each contribute to the overall emission. Multi-galaxy systems are challenging to model, because they add an extra 5-10 parameters to the non-linear search per galaxy and, more problematically, the degeneracies between the parameters of the light profiles of the galaxies can be severe.
+  - Contents: Initial Setup, Paths, Search Chaining Approach, Model + Search + Analysis + Model-Fit (Search 1), Result (Search 1), Model (Search 2), Search + Analysis + Model-Fit (Search 2), Result (Search 2), Model + Search + Analysis + Model-Fit (Search 4), Result (Search 3), Wrap Up
+
+## chapter_4_pixelizations
+
+- [Tutorial 1: pixelizations](scripts/chapter_4_pixelizations/tutorial_1_pixelizations.py): In the previous chapters, we used light profiles to model the light of a galaxy, where the light profile was an analytic description of how the luminosity varies as a function of radius.
+  - Contents: Initial Setup, Mesh, Wrap Up
+- [Tutorial 2: Mappers](scripts/chapter_4_pixelizations/tutorial_2_mappers.py): In the previous tutorial, we used a pixelization to create made a `Mapper`. However, it was not clear what a `Mapper` does, why it was called a mapper and whether it was mapping anything at all!
+  - Contents: Initial Setup, Mappers, Mask, Wrap Up
+- [Tutorial 3: Inversions](scripts/chapter_4_pixelizations/tutorial_3_inversions.py): In the previous two tutorials, we introduced:
+  - Contents: Initial Setup, Pixelization, Positive Only Solver, Wrap Up, Detailed Explanation
+- [Tutorial 4: Bayesian Regularization](scripts/chapter_4_pixelizations/tutorial_4_bayesian_regularization.py): So far, we have:
+  - Contents: Initial Setup, Convenience Function, Pixelization, Regularization, Bayesian Evidence, Non-Linear and Linear, Detailed Description
+- [Tutorial 5: Model-Fit](scripts/chapter_4_pixelizations/tutorial_5_model_fit.py): In the previous tutorials we used an inversion to reconstruct a complex galaxy. However, from the perspective of a scientific analysis, it is not clear how useful this was. When I fit a galaxy with light profiles, I learn about its brightness (`intensity`), size (`effective_radius`), compactness (`sersic_index`), etc.
+  - Contents: Initial Setup, Model + Search + Analysis + Model-Fit (Search 1), Mesh Shape, Model + Search + Analysis + Model-Fit (Search 2), Model + Search (Search 3), Wrap Up
+
+## chapter_optional
+
+- [Tutorial: Alternative Searches](scripts/chapter_optional/tutorial_searches.py): Up to now, we've always used the non-linear search Nautilus and not considered the input parameters that control its sampling. In this tutorial, we'll consider how we can change these setting to balance finding the global maxima solution with fast run time.
+  - Contents: Nested Sampling, Optimizers, MCMC
+
+## simulators
+
+- [Simulator: Sersic](scripts/simulators/sersic.py): This script simulates `Imaging` of a galaxy using light profiles where:
+  - Contents: Dataset Paths, Grid, Galaxies, Output, Visualize, Plane Output
+- [Simulator: Sersic x2](scripts/simulators/sersic_x2.py): This script simulates `Imaging` of two galaxies where:
+  - Contents: Dataset Paths, Grid, Galaxies, Output, Visualize, Plane Output
+- [Simulator: Sersic + Exp](scripts/simulators/simple.py): This script simulates `Imaging` of a galaxy using light profiles where:
+  - Contents: Dataset Paths, Grid, Over Sampling, Galaxies, Output, Visualize, Plane Output

llms.txt

@@ -0,0 +1,80 @@
+If your AI can't browse GitHub, paste this entire file into the chat as context.
+
+# HowToGalaxy
+
+> The **HowToGalaxy** lecture series: tutorial scripts (and generated notebooks) that teach
+> galaxy morphology and the **PyAutoGalaxy** API from first principles. This file is a
+> routing layer: given a learner's question, point them to the RIGHT existing tutorial in
+> this repository instead of inventing an explanation. Every path below is a real file in
+> this repo; scripts run from the repo root (e.g. `python scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py`),
+> and each has a matching notebook under `notebooks/`.
+
+## Who this is for
+
+HowToGalaxy is the **on-ramp for beginners** — students new to galaxy structure analysis, or
+new to PyAutoGalaxy. It teaches the concepts and the API step by step. Once a learner wants
+to run a real analysis on their own data, route them *out* to the production examples in
+[autogalaxy_workspace](https://github.com/PyAutoLabs/autogalaxy_workspace) (see "Ready for
+real analysis?" below).
+
+## Start here
+
+- [start_here.ipynb](start_here.ipynb): One-page orientation — what the lectures cover and how to run them (locally or in Colab).
+- [scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py](scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py): The first real lecture — galaxy morphology (the Hubble tuning fork), grids, geometry and light profiles. Begin here if the learner is new to galaxy structure.
+
+## The learning path (chapters in order)
+
+- **Chapter 1 — Introduction** → [scripts/chapter_1_introduction/](scripts/chapter_1_introduction/): Galaxies from first principles: grids & galaxies, light profiles, simulating data, and fitting data. The conceptual foundation.
+- **Chapter 2 — Modeling** → [scripts/chapter_2_modeling/](scripts/chapter_2_modeling/): Fitting a galaxy model to data with a non-linear search — parameter spaces, priors, dealing with failure, linear light profiles, masking, and reading results.
+- **Chapter 3 — Search Chaining** → [scripts/chapter_3_search_chaining/](scripts/chapter_3_search_chaining/): Breaking a hard fit into a sequence of searches (prior passing) and modeling multi-galaxy images.
+- **Chapter 4 — Pixelizations** → [scripts/chapter_4_pixelizations/](scripts/chapter_4_pixelizations/): Reconstructing irregular galaxy structure on a pixel-grid instead of with light profiles — mappers, inversions, Bayesian regularization.
+
+## I want to understand…
+
+- **What is a light profile / how is a galaxy's light described?** → [scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py](scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py): Sersic profiles, geometry, projecting light in 1D.
+- **How does a telescope image (and noise/PSF) get simulated?** → [scripts/chapter_1_introduction/tutorial_2_data.py](scripts/chapter_1_introduction/tutorial_2_data.py): Optics blurring, Poisson noise, background sky, the simulator API.
+- **What does "fitting" a galaxy mean?** → [scripts/chapter_1_introduction/tutorial_3_fitting.py](scripts/chapter_1_introduction/tutorial_3_fitting.py): Masking, model images, residuals and the log likelihood.
+- **How does a non-linear search find a model?** → [scripts/chapter_2_modeling/tutorial_1_non_linear_search.py](scripts/chapter_2_modeling/tutorial_1_non_linear_search.py): Parameter space, priors, MLE / MCMC / nested sampling.
+- **My fit found a wrong (local-maxima) solution — what do I do?** → [scripts/chapter_2_modeling/tutorial_4_dealing_with_failure.py](scripts/chapter_2_modeling/tutorial_4_dealing_with_failure.py): Prior tuning, reducing complexity, and looking harder.
+- **What are linear light profiles / MGE?** → [scripts/chapter_2_modeling/tutorial_5_linear_profiles.py](scripts/chapter_2_modeling/tutorial_5_linear_profiles.py): Solving intensities linearly; the Multi-Gaussian Expansion basis.
+- **How do I model an image with two galaxies?** → [scripts/chapter_3_search_chaining/tutorial_3_x2_galaxies.py](scripts/chapter_3_search_chaining/tutorial_3_x2_galaxies.py): Search chaining to handle multi-galaxy degeneracies.
+- **How do I reconstruct irregular structure on a pixel grid?** → [scripts/chapter_4_pixelizations/tutorial_1_pixelizations.py](scripts/chapter_4_pixelizations/tutorial_1_pixelizations.py) through [tutorial_4_bayesian_regularization.py](scripts/chapter_4_pixelizations/tutorial_4_bayesian_regularization.py).
+
+## Ready for real analysis?
+
+When the learner wants to model their *own* galaxy (not a teaching dataset), route them to
+the production workspace — it has science-case entry points and a data-preparation guide:
+
+- [autogalaxy_workspace](https://github.com/PyAutoLabs/autogalaxy_workspace) — see its own `llms.txt` routing layer; e.g. `imaging/start_here.py` for CCD data and its data-preparation guide for getting their FITS files analysis-ready.
+
+## How to answer (for the assistant)
+
+When routing a learner, reply in this shape (the same shape the workspace navigator uses, so
+the two agree):
+
+- **Start here** — the single best tutorial for their question (from the lists above).
+- **Then see** — the next tutorial in the chapter, or the concept it builds toward.
+- **Related guide** — a relevant later chapter, or the matching `autogalaxy_workspace` example for production use.
+- **Why this is the right example** — one line tying the tutorial to their question.
+- **What to modify** — the few things they'd change to explore (model components, dataset, search settings).
+- **What needs local execution** — flag any step that requires actually running the fit on their machine.
+
+### Code style (match the lectures, not banner comments)
+
+Drafted code must match this repo's style: triple-quoted `"""__Section__"""` docstrings with
+a line of prose explaining each step, and a module docstring whose title is underlined with
+`=`. Do NOT use `# -----` banner comments to mark sections; reserve inline `#` for short
+line-level notes only.
+
+## Capability boundary (chat without local execution)
+
+A chat assistant can route to the right tutorial, explain galaxy-structure concepts, review
+pasted scripts / tracebacks / plots, and draft code. It CANNOT run fits, inspect the
+learner's local files or `output/` folder, or guarantee code against their installed
+PyAutoGalaxy version. To run a tutorial, the learner executes it locally from the repo root,
+or in Google Colab (the notebooks ship Colab setup cells). For sustained editing, execution
+and project state, point them to a local coding agent (Claude Code / Codex).
+
+---
+
+For the full per-tutorial listing, see the generated companion catalogue `llms-full.txt`.