PyAutoLabs · Jammy2211 · May 4, 2026 · May 4, 2026
diff --git a/CITATIONS.md b/CITATIONS.md
@@ -0,0 +1,16 @@
+# Citations & References
+
+The bibtex entries for **PyAutoGalaxy** and its affiliated software packages can be found
+[here](https://github.com/Jammy2211/PyAutoGalaxy/blob/main/files/citations.bib), with example text for citing **PyAutoGalaxy**
+in [.tex format here](https://github.com/Jammy2211/PyAutoGalaxy/blob/main/files/citations.tex) format here and
+[.md format here](https://github.com/Jammy2211/PyAutoGalaxy/blob/main/files/citations.md).
+
+As shown in the examples, we would greatly appreciate it if you mention **PyAutoGalaxy** by name and include a link to
+our GitHub page!
+
+**PyAutoGalaxy** is published in the [Journal of Open Source Software](https://joss.theoj.org/papers/10.21105/joss.02825#) and its
+entry in the above .bib file is under the citation key `pyautogalaxy`.
+
+You should also specify the non-linear search(es) you use in your analysis (e.g. Dynesty, Emcee, PySwarms, etc) in
+the main body of text, and delete as appropriate any packages your analysis did not use. The citations.bib file includes
+the citation key for all of these projects.
diff --git a/CITATIONS.rst b/CITATIONS.rst
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,8 +1,8 @@
 # MANIFEST.in
 exclude .gitignore
-include README.rst
+include README.md
 include setup.cfg
-include CITATIONS.rst
+include CITATIONS.md
 include LICENSE
 include requirements.txt
 include optional_requirements.txt

diff --git a/README.md b/README.md
@@ -0,0 +1,72 @@
+# PyAutoGalaxy: Open-Source Multi Wavelength Galaxy Structure & Morphology
+
+[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/PyAutoLabs/autogalaxy_workspace/blob/2026.5.1.4/start_here.ipynb)
+[![Documentation Status](https://readthedocs.org/projects/pyautogalaxy/badge/?version=latest)](https://pyautogalaxy.readthedocs.io/en/latest/?badge=latest)
+[![Tests](https://github.com/Jammy2211/PyAutoGalaxy/actions/workflows/main.yml/badge.svg)](https://github.com/Jammy2211/PyAutoGalaxy/actions)
+[![Build](https://github.com/Jammy2211/PyAutoBuild/actions/workflows/release.yml/badge.svg)](https://github.com/Jammy2211/PyAutoBuild/actions)
+[![Code Style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![JOSS](https://joss.theoj.org/papers/10.21105/joss.04475/status.svg)](https://doi.org/10.21105/joss.04475)
+[![pyOpenSci Peer-Reviewed](https://pyopensci.org/badges/peer-reviewed.svg)](https://github.com/pyOpenSci/software-submission/issues/235)
+[![Zenodo DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.7546914.svg)](https://doi.org/10.5281/zenodo.7546914)
+[![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
+[![Python Versions](https://img.shields.io/pypi/pyversions/autogalaxy)](https://pypi.org/project/autogalaxy/)
+[![PyPI Version](https://img.shields.io/pypi/v/autogalaxy.svg)](https://pypi.org/project/autogalaxy/)
+
+[Installation Guide](https://pyautogalaxy.readthedocs.io/en/latest/installation/overview.html) |
+[readthedocs](https://pyautogalaxy.readthedocs.io/en/latest/index.html) |
+[Introduction on Colab](https://colab.research.google.com/github/PyAutoLabs/autogalaxy_workspace/blob/2026.5.1.4/start_here.ipynb) |
+[HowToGalaxy](https://pyautogalaxy.readthedocs.io/en/latest/howtogalaxy/howtogalaxy.html)
+
+**PyAutoGalaxy** is software for analysing the morphologies and structures of galaxies:
+
+[![HST Combined](https://github.com/Jammy2211/PyAutoGalaxy/blob/main/paper/hstcombined.png?raw=true)](https://github.com/Jammy2211/PyAutoGalaxy/blob/main/paper/hstcombined.png)
+
+**PyAutoGalaxy** also fits interferometer data from observatories such as ALMA:
+
+[![ALMA Combined](https://github.com/Jammy2211/PyAutoGalaxy/blob/main/paper/almacombined.png?raw=true)](https://github.com/Jammy2211/PyAutoGalaxy/blob/main/paper/almacombined.png)
+
+## Getting Started
+
+The following links are useful for new starters:
+
+- [The PyAutoGalaxy readthedocs](https://pyautogalaxy.readthedocs.io/en/latest), which includes [an overview of PyAutoGalaxy's core features](https://pyautogalaxy.readthedocs.io/en/latest/overview/overview_1_start_here.html), [a new user starting guide](https://pyautogalaxy.readthedocs.io/en/latest/overview/overview_2_new_user_guide.html) and [an installation guide](https://pyautogalaxy.readthedocs.io/en/latest/installation/overview.html).
+- [The introduction Jupyter Notebook on Google Colab](https://colab.research.google.com/github/PyAutoLabs/autogalaxy_workspace/blob/2026.5.1.4/start_here.ipynb), where you can try **PyAutoGalaxy** in a web browser (without installation).
+- [The autogalaxy_workspace GitHub repository](https://github.com/PyAutoLabs/autogalaxy_workspace): example scripts covering every **PyAutoGalaxy** use case.
+- [The HowToGalaxy GitHub repository](https://github.com/PyAutoLabs/HowToGalaxy): a Jupyter notebook lecture series teaching galaxy modeling from the ground up.
+
+## Core Aims
+
+**PyAutoGalaxy** has three core aims:
+
+- **Big Data**: Scaling automated Sérsic fitting to extremely large datasets, *accelerated with JAX on GPUs and using tools like an SQL database to **build a scalable scientific workflow***.
+- **Model Complexity**: Fitting complex galaxy morphology models (e.g. Multi Gaussian Expansion, Shapelets, Ellipse Fitting, Irregular Meshes) that go beyond just simple Sérsic fitting.
+- **Data Variety**: Support for many data types (e.g. CCD imaging, interferometry, multi-band imaging) which can be fitted independently or simultaneously.
+
+A complete overview of the software's aims is provided in our [Journal of Open Source Software paper](https://joss.theoj.org/papers/10.21105/joss.04475).
+
+## Community & Support
+
+Support for **PyAutoGalaxy** is available via our Slack workspace, where the community shares updates, discusses
+galaxy modeling and analysis, and helps troubleshoot problems.
+
+Slack is invitation-only. If you'd like to join, please send an email requesting an invite.
+
+For installation issues, bug reports, or feature requests, please raise an issue on the [GitHub issues page](https://github.com/Jammy2211/PyAutoGalaxy/issues).
+
+## HowToGalaxy
+
+For users less familiar with galaxy analysis, Bayesian inference, and scientific analysis, you may wish to read through
+the **HowToGalaxy** lectures. These introduce the basic principles of galaxy modeling and Bayesian inference, with
+the material pitched at undergraduate level and above.
+
+A complete overview of the lectures [is provided on the HowToGalaxy readthedocs page](https://pyautogalaxy.readthedocs.io/en/latest/howtogalaxy/howtogalaxy.html), and the notebooks themselves live in the [PyAutoLabs/HowToGalaxy](https://github.com/PyAutoLabs/HowToGalaxy) repository.
+
+## Citations
+
+Information on how to cite **PyAutoGalaxy** in publications can be found [on the citations page](https://github.com/Jammy2211/PyAutoGalaxy/blob/main/CITATIONS.md).
+
+## Contributing
+
+Information on how to contribute to **PyAutoGalaxy** can be found [on the contributing page](https://github.com/Jammy2211/PyAutoGalaxy/blob/main/CONTRIBUTING.md).
+
+Hands on support for contributions is available via our Slack workspace, again please email to request an invite.
diff --git a/README.rst b/README.rst
diff --git a/autogalaxy/config/README.md b/autogalaxy/config/README.md
@@ -0,0 +1,13 @@
+The `config` folder contains configuration files which customize default **PyAutoLens**.
+
+# Folders
+
+- `priors`: Configs defining default priors assumed on every model component and set of parameters.
+- `visualize`: Configs defining what images are output by a lens model fit.
+
+# Files
+
+- `general.yaml`: Customizes general **PyAutoLens** settings.
+- `grids.yaml`: Customize default behaviour of grids when used for calculations.
+- `logging.yaml`: Customizes the logging behaviour.
+- `notation.yaml`: Configs defining labels and formatting of model parameters when used for visualization.
diff --git a/autogalaxy/config/README.rst b/autogalaxy/config/README.rst
diff --git a/autogalaxy/config/priors/README.md b/autogalaxy/config/priors/README.md
@@ -0,0 +1,41 @@
+The prior config files contain the default priors and related variables for every light profile and mass profile
+when it is used as a model.
+
+They appear as follows:
+
+```bash
+Sersic:
+  effective_radius:
+    type: Uniform
+    lower_limit: 0.0
+    upper_limit: 100.0
+    width_modifier:
+      type: Absolute
+      value: 20.0
+    limits:
+      lower: -inf
+      upper: inf
+```
+
+The sections of this example config set the following:
+
+> type {Uniform, Gaussian, LogUniform}
+>
+> : The default prior given to this parameter when used by the non-linear search. In the example above, a
+>   UniformPrior is used with lower_limit of 0.0 and upper_limit of 4.0. A GaussianPrior could be used by
+>   putting "Gaussian" in the "type" box, with "mean" and "sigma" used to set the default values. Any prior can be
+>   set in an analogous fashion (see the example configs).
+>
+> width_modifier
+>
+> : When the results of a search are passed to a subsequent search to set up the priors of its non-linear search,
+>   this entry describes how the Prior is passed.
+>
+> limits
+>
+> : When the results of a search are passed to a subsequent search, they are passed using a GaussianPrior. The
+>   limits set the physical lower and upper limits of this GaussianPrior, such that parameter samples
+>   can not go beyond these limits.
+
+The files `template_module.yaml` and `TemplateObject.yaml` give templates one can use to set up prior default
+configs for your own model components.
diff --git a/autogalaxy/config/priors/README.rst b/autogalaxy/config/priors/README.rst
diff --git a/autogalaxy/config/priors/ellipse/README.rst → autogalaxy/config/priors/ellipse/README.md b/autogalaxy/config/priors/ellipse/README.rst → autogalaxy/config/priors/ellipse/README.md
@@ -1,6 +1,6 @@
-The ``ellipse`` folder contains configuration files for the default priors assumed for ``ellipse`` objects.
-
-These model components are used for ellipse isophote fitting, which models the surface brightness of a galaxy as a
-series of ellipses, which can include multipole perturbations.
-
-The main object used for modeling is the `Ellipse` object, with a list of `Ellipse` objects used to model the galaxy.
+The `ellipse` folder contains configuration files for the default priors assumed for `ellipse` objects.
+
+These model components are used for ellipse isophote fitting, which models the surface brightness of a galaxy as a
+series of ellipses, which can include multipole perturbations.
+
+The main object used for modeling is the `Ellipse` object, with a list of `Ellipse` objects used to model the galaxy.
diff --git a/autogalaxy/config/priors/galaxy/README.md b/autogalaxy/config/priors/galaxy/README.md
@@ -0,0 +1,5 @@
+The `galaxy` folder contains configuration files for the default priors assumed for `Galaxy` object properties **PyAutoGalaxy**.
+
+# Folders
+
+- `redshift`: Configs for priors on the redshift of a galaxy, when treated as a free parameter.