docs: clarify assistant and documentation paths

[Jammy2211]

Overview

Improve the onboarding hierarchy across PyAutoLens and PyAutoGalaxy so the AI Assistant and human-readable documentation are visibly distinct routes. Repair the flattened workspace Getting Started layout and place the assistant at the top of both Read the Docs Start Here pages, without removing installation, Colab, or example links.

Plan

• Give the AI Assistant and human-readable documentation distinct subsection headings in each Getting Started section.
• Repair the workspace README layout by presenting installation and Colab as structured choices.
• Put the AI Assistant first on both Read the Docs Start Here pages.
• Separate assistant guidance from the conventional content on both New User Guide pages.
• Mirror the structure between PyAutoLens and PyAutoGalaxy and validate both documentation builds.

Detailed implementation plan

Work Classification

Both — coordinated library and workspace documentation changes; no API, source-code, script, or notebook changes.

Affected Repositories

• PyAutoLens (primary)
• PyAutoGalaxy
• autolens_workspace
• autogalaxy_workspace

Branch Survey

Repository	Current Branch	Dirty?
./PyAutoLens	main	clean
./PyAutoGalaxy	main	clean
./autolens_workspace	main	clean
./autogalaxy_workspace	main	clean

No affected repository is claimed by another active task.

Suggested branch: feature/assistant-docs-hierarchy

Worktree root: ~/Code/PyAutoLabs-wt/assistant-docs-hierarchy/

Implementation Steps

1. Add product-specific AI Assistant and Human-Readable Documentation and Examples subsection headings beneath Getting Started in PyAutoLens/README.md and PyAutoGalaxy/README.md.
2. Apply equivalent subsections to PyAutoLens/docs/index.md and PyAutoGalaxy/docs/index.md using the appropriate heading depth.
3. Put the AI Assistant directly below the title in both docs/overview/overview_1_start_here.md pages, followed by a distinct human-readable overview section.
4. Reorder and split both docs/overview/overview_2_new_user_guide.md pages into AI Assistant and Human-Readable Guide sections.
5. Add matching subsections to both workspace READMEs and convert the installation and Colab prose into a clean list of choices.
6. Run Markdown consistency checks, git diff --check, and both Sphinx documentation builds.

Key Files

• PyAutoLens/README.md and PyAutoGalaxy/README.md — library onboarding hierarchy.
• PyAutoLens/docs/index.md and PyAutoGalaxy/docs/index.md — RTD landing-page hierarchy.
• PyAutoLens/docs/overview/overview_1_start_here.md and PyAutoGalaxy/docs/overview/overview_1_start_here.md — assistant-first Start Here pages.
• PyAutoLens/docs/overview/overview_2_new_user_guide.md and PyAutoGalaxy/docs/overview/overview_2_new_user_guide.md — split assistant and human-readable guide routes.
• autolens_workspace/README.md and autogalaxy_workspace/README.md — repaired workspace Getting Started layout.

Original Prompt

Click to expand starting prompt

On the README.md page can you use smaller subsection heading to spit PyAutoLens AI Assistant and Human readable docs, or bold font, or something to make them appear a bit more separate and distinct as two options? The PyAutoLens AI Assistant supports conversation agents such as ChatGPT and coding agents such as Claude Code and Codex. You can get started simply by asking it a question about gravitational lensing or describing the task you would like to perform with PyAutoLens. See the assistant for its full scope and instructions.

The following human-readable documentation and examples are also useful for new starters: The formatting and strucutre on autolens_workspace is flat out broken: The following human-readable documentation and examples are also useful for new starters:

You can get set up on your personal computer by following the installation guide on our readthedocs.

Alternatively, you can try PyAutoLens out in a web browser by going to the autolens workspace on Colab. Also for formatting split on readthedocs lensing or describing the task you would like to perform with PyAutoLens. See the assistant for its full scope and instructions.

The rest of this human-readable guide begins with two simple questions to help you find the most appropriate example notebook for your science case. and also have the AI assistant section at the top of the "Start Here" page of each readthedocs

[Jammy2211]

Library PR Created

• PyAutoLens: docs: clarify assistant and documentation paths #648 — 448 tests passed; Sphinx build passed.
• PyAutoGalaxy: docs: clarify assistant and documentation paths PyAutoGalaxy#522 — 1,006 tests passed; Sphinx build passed.

API Changes

None — documentation-only changes.

Next: /start_workspace for the planned autolens_workspace and autogalaxy_workspace README hierarchy updates. These workspace changes are documentation-only and do not migrate an API.

[Jammy2211]

Smoke Test Results — 2026-07-24

All 19 smoke tests passed across both affected workspaces.

Workspace	Passed	Failed	Total
autolens_workspace	11	0	11
autogalaxy_workspace	8	0	8

Workspace PRs Created

• PyAutoLens: docs: clarify assistant and documentation paths #648
• PyAutoGalaxy: docs: clarify assistant and documentation paths PyAutoGalaxy#522
• autolens_workspace: docs: clarify assistant and documentation paths autolens_workspace#330
• autogalaxy_workspace: docs: clarify assistant and documentation paths autogalaxy_workspace#156

All four PRs are open against main with the pending-release label. This remains documentation-only work with no API, script, or notebook changes. The library PRs must merge before the matching workspace PRs; no PRs were merged in this run.

[Jammy2211]

Shipped — 2026-07-24

PRs

• docs: clarify assistant and documentation paths #648
• docs: clarify assistant and documentation paths PyAutoGalaxy#522
• docs: clarify assistant and documentation paths autolens_workspace#330
• docs: clarify assistant and documentation paths autogalaxy_workspace#156

Summary

Added distinct AI Assistant and Human-Readable Documentation sections across the PyAutoLens and PyAutoGalaxy library READMEs, RTD landing pages, RTD Start Here pages, New User Guides, and workspace READMEs. The workspace installation and Colab routes are now structured lists instead of flattened prose. All library tests, RTD builds, workspace smoke tests, and GitHub checks passed.

Session Notes

This was documentation-only: no API, scripts, or notebooks changed. Library PRs were merged before their matching workspace PRs.