docs(chapter_1): restore truncated tutorials + add completeness CI check

tutorial_1_grids_and_galaxies and tutorial_2_ray_tracing were cut off
mid-generation during the workspace bootstrap, each ending on a docstring that
promised a plot with no code following and no Wrap Up (frozen at the truncated
length since bootstrap commit #1; the original workspace source no longer
exists).

Restore the lost content:
- tutorial_1: log10 image + __Galaxies__ + __Units__ + __Wrap Up__ + advanced
  topics, adapted from the complete HowToGalaxy sibling to the autolens API and
  lens framing (429 -> 672 lines).
- tutorial_2: log-space convergence/potential + __Ray Tracing Grids__ (lens
  equation) + __Ray Tracing Images__ + __Galaxies__ + __Tracer__ + __Mappings__
  + __Wrap Up__, sourced from guides/tracer.py (214 -> 391 lines).

Both validated end-to-end and via the curated smoke suite (6/6).

Prevent recurrence: add .github/scripts/check_tutorials_complete.py + a CI
workflow that fails when any tutorial lacks a terminal __Wrap Up__/__Summary__
section — a truncated script never reaches its wrap-up, so absence of the marker
reliably flags lost content. Normalize five complete-but-unmarked tutorials
(tutorial_4_dealing_with_failure, tutorial_4_bayesian_regularization,
tutorial_6_slam, tutorial_8_model_fit, tutorial_searches) with the terminal
marker so they pass.

Regenerate notebooks + navigator catalogue.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KExk2jkn2ya21b6NZLALpB

Author: 2 people

.github/scripts/check_tutorials_complete.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Fail if any HowTo tutorial script looks truncated.
+
+Several tutorial scripts were once cut off mid-generation (a long file was
+re-emitted and the output was severed), losing all content below the cut and
+leaving a script that ends part-way through — typically on a docstring that
+promises a plot or code block which never appears. This check guards against
+that regression recurring.
+
+A tutorial is considered *complete* when it contains a recognised terminal
+section marker (``__Wrap Up__`` or ``__Summary__``). A truncated script never
+reaches its wrap-up, so the absence of the marker is a reliable signal that the
+script lost content. Deliberate "not written yet" stub tutorials still carry a
+``__Wrap Up__`` section, so they pass.
+
+A second, cheaper guard flags any script whose final docstring block ends on a
+colon (``:``) — the classic "a plot/code block follows" promise left dangling
+by a mid-docstring cutoff.
+
+Run from the repo root::
+
+    python scripts/check_tutorials_complete.py
+
+Exit status is non-zero if any tutorial fails, listing each offender.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+TERMINAL_MARKERS = ("__wrap up__", "__summary__")
+
+
+def final_docstring(text: str) -> str | None:
+    """Return the last triple-quoted block if it sits at the end of the file."""
+    blocks = list(re.finditer(r'"""(.*?)"""', text, re.DOTALL))
+    if not blocks:
+        return None
+    last = blocks[-1]
+    if text[last.end():].strip() == "":
+        return last.group(1)
+    return None
+
+
+def check(path: Path) -> str | None:
+    """Return a failure reason for a truncated-looking tutorial, else None."""
+    text = path.read_text(encoding="utf-8")
+    if not any(marker in text.lower() for marker in TERMINAL_MARKERS):
+        return "no __Wrap Up__/__Summary__ terminal section (looks truncated)"
+    trailing = final_docstring(text)
+    if trailing is not None and trailing.strip().endswith(":"):
+        return "final docstring ends on ':' (dangling promise of a following block)"
+    return None
+
+
+def main(root: str) -> int:
+    scripts_dir = Path(root) / "scripts"
+    files = sorted(scripts_dir.rglob("tutorial_*.py"))
+
+    failures = [(f, reason) for f in files if (reason := check(f)) is not None]
+
+    print(f"Checked {len(files)} tutorial scripts under {scripts_dir}.")
+    if failures:
+        print(f"\n{len(failures)} tutorial(s) look incomplete / truncated:\n")
+        for f, reason in failures:
+            print(f"  [FAIL] {f.relative_to(root)} — {reason}")
+        print(
+            "\nEach tutorial must end with a `__Wrap Up__` (or `__Summary__`) "
+            "section. If a script is genuinely truncated, restore its lost "
+            "content; if it is complete, add the terminal section."
+        )
+        return 1
+
+    print("All tutorial scripts have a terminal section — none look truncated.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1] if len(sys.argv) > 1 else "."))

.github/workflows/tutorials_complete.yml

@@ -0,0 +1,20 @@
+name: Tutorials Complete
+
+# Guards against tutorial scripts being truncated / cut off mid-generation (a
+# long file re-emitted with the output severed, losing every section below the
+# cut). Each tutorial_*.py must end with a `__Wrap Up__` (or `__Summary__`)
+# terminal section; the check is pure-stdlib and needs no library install.
+# See scripts/check_tutorials_complete.py.
+
+on: [push, pull_request]
+
+jobs:
+  tutorials-complete:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Check tutorials are not truncated
+        run: python .github/scripts/check_tutorials_complete.py .

llms-full.txt

@@ -12,9 +12,9 @@ AUTO-GENERATED by PyAutoBuild — do not edit by hand; regenerate with generate.
 - [Tutorial 0: Visualization](scripts/chapter_1_introduction/tutorial_0_visualization.py): In this tutorial, we quickly cover visualization in **PyAutoLens** and make sure images display clearly in your Jupyter notebook and on your computer screen.
   - Contents: Directories, Dataset, Subplots, Plot Customization, Overlays, Wrap Up
 - [HowToLens: Introduction](scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py): A strong gravitational lens is a system where two (or more) galaxies align perfectly down our line of sight from Earth such that the foreground galaxy's mass curves space-time in on itself, such that the light of a background source galaxy is deflected and magnified. This means we can see the background source galaxy multiple times, as multiple arcs or rings, because multiple paths through the foreground galaxy's mass are taken by the source's light.
-  - Contents: Grids, Geometry, Light Profiles, One Dimension Projection
+  - Contents: Grids, Geometry, Light Profiles, One Dimension Projection, Galaxies, Units
 - [Tutorial 2: Ray Tracing](scripts/chapter_1_introduction/tutorial_2_ray_tracing.py): Strong gravitational lensing occurs when the mass of a foreground galaxy (or galaxies) curves space-time around it, causing light rays from a background source to appear deflected.
-  - Contents: Grid, Mass Profiles
+  - Contents: Grid, Mass Profiles, Ray Tracing Grids, Ray Tracing Images, Galaxies, Tracer, Mappings
 - [Tutorial 5: More Ray Tracing](scripts/chapter_1_introduction/tutorial_3_more_ray_tracing.py): We'll now reinforce the ideas that we learnt about ray-tracing in the previous tutorial and introduce the following new concepts:
   - Contents: Initial Setup, Concise Code, Critical Curves, Caustics, Units, More Complexity, Multi Galaxy Ray Tracing, Wrap Up
 - [Tutorial 4: Point Sources](scripts/chapter_1_introduction/tutorial_4_point_sources.py): This tutorial is not wrriten yet, but will explain how point source lensing works.