docs: correct top-level guidance and remove obsolete files

.url_check_allowlist.txt

@@ -8,21 +8,16 @@
 
 # Academic citations (paywall / DOI / journal)
 https://academic.oup.com/mnras/article-abstract/478/4/4738/5001434?redirectedFrom=fulltext  # CITATIONS.md:11
-https://academic.oup.com/mnras/article-abstract/489/2/2049/5550746  # docs/index.md:35
-https://academic.oup.com/mnras/article/442/3/2017/1048278  # docs/index.md:36
 https://academic.oup.com/mnras/article/452/3/2940/1749640  # CITATIONS.md:11
-https://academic.oup.com/mnras/article/468/3/2590/3055701  # docs/index.md:37
 https://academic.oup.com/mnras/article/488/1/1387/5526256  # CITATIONS.md:22
 
 # Code of Conduct boilerplate
-http://geekfeminism.wikia.com/wiki/Conference_anti-harassment/Policy  # CODE_OF_CONDUCT.md:305
 
 # External dead / paywalled / departmental pages
 http://www.ita.uni-heidelberg.de/~massimo/sub/Lectures/gl_all.pdf  # docs/howtolens/howtolens.md:36
 https://bitbucket.org/bdiemer/colossus/src/main/  # files/citations.md:12
 
 # GitHub refs (workspaces / removed tutorials)
-https://github.com/PyAutoLabs/autolens_workspace/blob/main/notebooks/imaging/advanced/chaining/start_here.ipynb  # docs/general/model_cookbook.md:384
 https://github.com/PyAutoLabs/autolens_workspace/blob/main/scripts/imaging/preprocess/gui/positions.py  # docs/general/demagnified_solutions.md:73
 
 # Internal PyAuto docs — pages renamed, need editorial fix

AGENTS.md

@@ -75,7 +75,7 @@ parity scripts in `autolens_workspace_test` (`jax.jit` round-trip +
 `fitness._vmap` batch eval) — never by `test_autolens/`.
 
 Full detail lives in PyAutoArray:
-**[`PyAutoArray/docs/agents/jax_and_decorators.md`](../PyAutoArray/docs/agents/jax_and_decorators.md)**.
+**[`PyAutoArray/docs/agents/jax_and_decorators.md`](https://github.com/PyAutoLabs/PyAutoArray/blob/main/docs/agents/jax_and_decorators.md)**.
 
 ## Public API
 
@@ -108,7 +108,7 @@ Profiles re-export from autogalaxy (`al.mp.*`, `al.lp.*`) alongside `al.Galaxy`,
 
 ## Deep dives
 
-- [`PyAutoArray/docs/agents/jax_and_decorators.md`](../PyAutoArray/docs/agents/jax_and_decorators.md)
+- [`PyAutoArray/docs/agents/jax_and_decorators.md`](https://github.com/PyAutoLabs/PyAutoArray/blob/main/docs/agents/jax_and_decorators.md)
   — decorator system, `xp` backend pattern, and the `jax.jit` boundary.
 
 <!-- repos_sync:history:begin -->

CODE_OF_CONDUCT.md

@@ -2,4 +2,4 @@
 
 PyAutoLabs uses one Code of Conduct across all of its repositories.
 
-Read the [canonical PyAutoLabs Code of Conduct](https://github.com/PyAutoLabs/PyAutoScientist/blob/main/CODE_OF_CONDUCT.md).
+Read the [canonical PyAutoLabs Code of Conduct](https://github.com/PyAutoLabs/.github/blob/main/CODE_OF_CONDUCT.md).

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 PyAutoLabs maintains its shared contribution guidance in one place.
 
-Read the [canonical PyAutoLabs contribution guide](https://github.com/PyAutoLabs/PyAutoScientist/blob/main/CONTRIBUTING.md).
+Read the [canonical PyAutoLabs contribution guide](https://github.com/PyAutoLabs/.github/blob/main/CONTRIBUTING.md).
 
 Repository-specific setup, test commands, and editing rules are documented in
 that repository's `README.md` and `AGENTS.md`, where present.

README.md

@@ -1,27 +1,8 @@
 # PyAutoLens-JAX: Open-Source Strong Lensing
 
-[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/PyAutoLabs/autolens_workspace/blob/2026.11.9.1/start_here.ipynb)
-[![Documentation Status](https://readthedocs.org/projects/pyautolens/badge/?version=latest)](https://pyautolens.readthedocs.io/en/latest/?badge=latest)
-[![Tests](https://github.com/PyAutoLabs/PyAutoLens/actions/workflows/main.yml/badge.svg)](https://github.com/PyAutoLabs/PyAutoLens/actions)
-[![Build](https://github.com/PyAutoLabs/PyAutoHands/actions/workflows/release.yml/badge.svg)](https://github.com/PyAutoLabs/PyAutoHands/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.02825/status.svg)](https://doi.org/10.21105/joss.02825)
-[![Zenodo DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4548697.svg)](https://doi.org/10.5281/zenodo.4548697)
-[![arXiv](https://img.shields.io/badge/arXiv-1708.07377-blue)](https://arxiv.org/abs/1708.07377)
-[![Project Status: Active](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
-[![Python Versions](https://img.shields.io/pypi/pyversions/autolens)](https://pypi.org/project/autolens/)
-[![PyPI Version](https://img.shields.io/pypi/v/autolens.svg)](https://pypi.org/project/autolens/)
-
-[Installation Guide](https://pyautolens.readthedocs.io/en/latest/installation/overview.html) |
-[readthedocs](https://pyautolens.readthedocs.io/en/latest/index.html) |
-[Introduction on Colab](https://colab.research.google.com/github/PyAutoLabs/autolens_workspace/blob/2026.11.9.1/start_here.ipynb) |
-[HowToLens](https://pyautolens.readthedocs.io/en/latest/howtolens/howtolens.html)
-
 <img src="https://github.com/Jammy2211/PyAutoLogo/blob/main/gifs/pyautolens.gif?raw=true" width="900" />
 
-When two or more galaxies are aligned perfectly down our line-of-sight, the background galaxy appears multiple times.
-
-This is called strong gravitational lensing and **PyAutoLens** makes it **simple** to model strong gravitational lenses, using JAX to **accelerate lens modeling on GPUs**.
+**PyAutoLens** lets you simulate and model strong gravitational lenses, using JAX to accelerate lens modeling on GPUs. Explore examples, analyse your own observations and learn how lensing reveals the galaxies and matter along our line of sight.
 
 ## Getting Started
 
@@ -31,49 +12,39 @@ This is called strong gravitational lensing and **PyAutoLens** makes it **simple
 - **[Try it in your browser](https://colab.research.google.com/github/PyAutoLabs/autolens_workspace/blob/2026.11.9.1/start_here.ipynb)** — run the introductory notebook without installing anything.
 - **[Install PyAutoLens](https://pyautolens.readthedocs.io/en/latest/installation/overview.html)** — get set up on your computer.
 
-Explore more examples in the [workspace](https://github.com/PyAutoLabs/autolens_workspace), or learn lensing from the ground up with [HowToLens](https://github.com/PyAutoLabs/HowToLens).
+Visit the [workspace](https://github.com/PyAutoLabs/autolens_workspace#find-your-examples) to find examples for your data and science goals.
 
 ### Explore with AI
 
-The [**PyAutoLens AI Assistant**](https://github.com/PyAutoLabs/autolens_assistant) lets you explore
-gravitational lensing through conversation. Ask a question, explore an idea, or describe the analysis
-you want to run. Both routes use the same software. To get started, paste this prompt into Claude Code, Codex
-or another AI coding agent:
-
-<sub><b>Starting prompt for Claude Code, Codex or other AI coding agent</b></sub>
+The [**PyAutoLens AI Assistant**](https://github.com/PyAutoLabs/autolens_assistant) helps you learn lensing, run examples and analyse your own data through conversation. To get started, paste this prompt into your AI coding agent:
 
 ```text
-I want to do strong lensing science with PyAutoLens (https://github.com/PyAutoLabs/PyAutoLens) and the
-autolens_assistant (https://github.com/PyAutoLabs/autolens_assistant). First clone that repository,
-cd into it and follow its AGENTS.md.
+I want to do strong lensing science with PyAutoLens
+(https://github.com/PyAutoLabs/PyAutoLens) and the
+autolens_assistant (https://github.com/PyAutoLabs/autolens_assistant).
 
+First clone the assistant repository, cd into it and follow its AGENTS.md.
 Begin the "start here" guide for a new user.
 ```
 
-The assistant guides you through [Start Here](https://pyautolens.readthedocs.io/en/latest/overview/overview_1_start_here.html)
-as a conversation, then helps you analyse your own lenses. See [AI Options](https://github.com/PyAutoLabs/PyAutoScientist/blob/main/AI_OPTIONS.md)
-for recommended tools, costs and free alternatives.
+See [AI Options](https://github.com/PyAutoLabs/PyAutoScientist/blob/main/AI_OPTIONS.md) for tools and setup guidance.
 
-## Community & Contributing
+## Learn Lensing
 
-**PyAutoLens** is built in the open by its users: everyone is welcome to ask questions,
-share what they have made with it, and contribute.
+[**HowToLens**](https://github.com/PyAutoLabs/HowToLens) teaches gravitational lensing and Bayesian inference through worked notebooks, starting from undergraduate level.
 
-Questions, ideas and bug reports: the [PyAutoLabs Discussions](https://github.com/orgs/PyAutoLabs/discussions).
-Chat with us on [Slack](https://join.slack.com/t/pyautolens/shared_invite/zt-2cufp4eyf-fXfgMxRGuvg~bMrI3uOAxg).
+The [PyAutoLens documentation](https://pyautolens.readthedocs.io/en/latest/index.html) covers the software’s features and how to use them in your own analysis.
 
-Community-built tools and tutorials, and how to contribute: the [**PyAutoLens** community page](https://pyautolens.readthedocs.io/en/latest/general/community.html).
+## Community and Contributing
 
-## HowToLens
+Ask questions, suggest improvements and share your work in [PyAutoLabs Discussions](https://github.com/orgs/PyAutoLabs/discussions), or chat with us on [Slack](https://join.slack.com/t/pyautolens/shared_invite/zt-2cufp4eyf-fXfgMxRGuvg~bMrI3uOAxg).
 
-For users less familiar with gravitational lensing, Bayesian inference and scientific analysis
-you may wish to read through the **HowToLens** lectures. These teach you the basic principles of gravitational lensing
-and Bayesian inference, with the content pitched at undergraduate level and above.
-
-A complete overview of the lectures [is provided on the HowToLens readthedocs page](https://pyautolens.readthedocs.io/en/latest/howtolens/howtolens.html), and the notebooks themselves live in the [PyAutoLabs/HowToLens](https://github.com/PyAutoLabs/HowToLens) repository.
+To contribute or explore community projects, visit the [PyAutoLens community page](https://pyautolens.readthedocs.io/en/latest/general/community.html).
 
 ## Citations
 
-Information on how to cite **PyAutoLens** in publications can be found [on the citations page](https://github.com/PyAutoLabs/PyAutoLens/blob/main/CITATIONS.md).
+If you use PyAutoLens in your research, see the [citation guide](https://github.com/PyAutoLabs/PyAutoLens/blob/main/CITATIONS.md).
+
+## License
 
-<sub><i><a href="https://open.spotify.com/track/6Ao5d7TMQ92h87jQqSHGyw">i found you, i found you, i found you beautiful, exploding, i found you</a></i></sub>
+See the [license](https://github.com/PyAutoLabs/PyAutoLens/blob/main/LICENSE).