refactor: fix folder-list drift in workspace/HowTo prose

[Jammy2211]

Overview

The 2026-08-19 hygiene refs scan found 18 folder-list defects in workspace/HowTo prose. Adjudication against the repos the prose actually names reduced this to 12 real defects (4 dead-reference lines + 8 undocumented README folder entries) across 5 repos; 6 findings are scanner sibling-repo false positives (targets exist in autolens_workspace) and need no edit. Prose-only — no code path, output, or public API changes.

Plan

• Fix the two autoCTI_workspace/output casing references in autocti_workspace modeling start_here scripts.
• Re-point howtolens/dataset/cluster/simple to dataset/cluster/simple (×2) in HowToLens simulator/cluster.py, matching sibling simulator prose.
• Add the 8 missing README folder-list entries (autofit, autogalaxy ×5, HowToGalaxy, HowToLens), each sourced from the target folder's own README or script docstrings — never inferred from the folder name.
• Leave the 6 adjudicated false positives untouched (valid cross-repo references into autolens_workspace).
• Regenerate notebook twins only where the repo's own AGENTS.md requires it; verify with a hygiene refs re-scan.

Detailed implementation plan

Affected Repositories

• autogalaxy_workspace (primary)
• autocti_workspace
• autofit_workspace
• HowToGalaxy
• HowToLens

Branch Survey

Repository	Current Branch	Dirty?
./autocti_workspace	main	clean
./autofit_workspace	main	clean
./autogalaxy_workspace	main	clean
./HowToGalaxy	main	clean
./HowToLens	main	clean

No worktree claims or conflicts (worktree_check_conflict exit 0). One unregistered stray local branch in autogalaxy_workspace (feature/stored-sample-reconstruction-guard) — pre-existing, not a conflict.

Suggested branch: feature/folder-list-ref-drift-sweep
Worktree root: ~/Code/PyAutoLabs-wt/folder-list-ref-drift-sweep/
Work Classification: Workspace

Implementation Steps

1. autocti_workspace — scripts/dataset_1d/modeling/start_here.py:363 and scripts/imaging_ci/modeling/start_here.py:387: change `autoCTI_workspace/output` → `autocti_workspace/output` (the lowercase form used everywhere else in the repo's prose). AGENTS.md says notebook regeneration is release-time — script-only PR.
2. HowToLens — scripts/simulator/cluster.py:77 and :528: change `howtolens/dataset/cluster/simple` → `dataset/cluster/simple` (script writes Path("dataset", "cluster", "simple"); siblings group.py/interferometer.py/weak_lensing.py use the bare repo-relative form).
3. README folder-list entries (source each description from the folder's own README/docstring):
   • autofit_workspace scripts/README.md: add cookbooks/
   • autogalaxy_workspace scripts/guides/results/README.md: add aggregator/, workflow/
   • autogalaxy_workspace scripts/imaging/data_preparation/README.md: add gui/, manual/
   • autogalaxy_workspace scripts/imaging/features/README.md: add point_source/
   • HowToGalaxy scripts/README.md: add simulators/
   • HowToLens scripts/README.md: add simulator/
4. Do NOT edit (adjudicated false positives, correct as written):
   • HowToLens tutorial_3_scaling_relation.py:575 imaging/features/scaling_relation — exists in autolens_workspace/scripts/imaging/features/scaling_relation/
   • HowToLens tutorial_6_weak_lensing.py:412-415 weak/{start_here,fit,modeling,simulator,likelihood_function}.py — all exist under autolens_workspace/scripts/weak/ (same adjudication as the 2026-08-06 hygiene pass)
5. Notebook twins: before each repo's PR, read that repo's AGENTS.md "Notebooks vs Scripts" section; where regeneration-with-PR is required, run PyAutoHands generate.py from inside the workspace and commit only the touched scripts' twins.
6. Witness: re-run PyAutoBrain/bin/pyauto-brain hygiene refs — the 12 real findings clear, no new ones; the 6 sibling-repo false positives remain until the scanner learns cross-repo resolution. .py diffs must touch only triple-quoted docstring prose.

Key Files

• autocti_workspace/scripts/dataset_1d/modeling/start_here.py — casing fix
• autocti_workspace/scripts/imaging_ci/modeling/start_here.py — casing fix
• HowToLens/scripts/simulator/cluster.py — dataset-path re-point ×2
• autofit_workspace/scripts/README.md, autogalaxy_workspace/scripts/guides/results/README.md, autogalaxy_workspace/scripts/imaging/data_preparation/README.md, autogalaxy_workspace/scripts/imaging/features/README.md, HowToGalaxy/scripts/README.md, HowToLens/scripts/README.md — missing folder entries

Original Prompt

Click to expand starting prompt

Fix folder-list drift in workspace/HowTo prose (hygiene refs sweep)

Type: refactor
Target: workspaces
Repos:

• autocti_workspace
• autofit_workspace
• autogalaxy_workspace
• HowToGalaxy
• HowToLens
  Difficulty: easy
  Autonomy: safe
  Priority: low
  Status: formalised

The 2026-08-19 hygiene refs scan found 18 folder-list defects (10 dead
references, 8 undocumented folders) in 11 files across 5 repos. Prose-only:
no code path, output, or public API changes.

Dead references — adjudicated 2026-08-19 (each -> finding judged against the
repo the surrounding sentence names, per the known sibling-repo false-positive
mode of the scanner):

REAL (fix):

• @autocti_workspace scripts/dataset_1d/modeling/start_here.py:363 and
  scripts/imaging_ci/modeling/start_here.py:387: autoCTI_workspace/output
  -> autocti_workspace/output (casing drift; the lowercase form is the one
  used everywhere else in the repo's prose).
• @HowToLens scripts/simulator/cluster.py:77 and :528:
  howtolens/dataset/cluster/simple -> dataset/cluster/simple (the script
  writes to Path("dataset", "cluster", "simple"); sibling simulators
  group.py/interferometer.py/weak_lensing.py all use the bare
  repo-relative form).

FALSE POSITIVES (no edit — correct as written, targets exist in
autolens_workspace which the prose names explicitly):

• @HowToLens tutorial_3_scaling_relation.py:575 imaging/features/scaling_relation
  (exists: autolens_workspace/scripts/imaging/features/scaling_relation/).
• @HowToLens tutorial_6_weak_lensing.py:412-415 weak/{start_here,fit,modeling,simulator,likelihood_function}.py
  (all exist under autolens_workspace/scripts/weak/; same adjudication as the
  2026-08-06 hygiene pass).

Undocumented folders (!! = folder exists, its README folder list never names
it; the fix is a new entry describing it, sourced from that folder's own README
or a script docstring — never inferred from the folder name):

• @autofit_workspace scripts/README.md !! cookbooks/
• @autogalaxy_workspace scripts/guides/results/README.md !! aggregator/, workflow/
• @autogalaxy_workspace scripts/imaging/data_preparation/README.md !! gui/, manual/
• @autogalaxy_workspace scripts/imaging/features/README.md !! point_source/
• @howtogalaxy scripts/README.md !! simulators/
• @HowToLens scripts/README.md !! simulator/

Behaviour-preservation invariant: .py edits touch only module-level
triple-quoted docstring prose (and README.md files); regenerated notebooks
must show prose-cell diffs only. Witness: re-run
PyAutoBrain/bin/pyauto-brain hygiene refs — the 12 real findings clear and no
new ones appear (the 6 sibling-repo false positives above will still be
reported by the scanner until it learns cross-repo resolution); smoke legs for
the touched scripts stay green. Notebook-regen convention is per-workspace —
check each repo's own AGENTS.md before opening its PR.

[Jammy2211]

Shipped — 2026-08-19 (PRs open, awaiting merge)

PRs

• docs: fix autoCTI_workspace/output casing in modeling start_here prose autocti_workspace#23
• docs: add cookbooks folder to scripts README autofit_workspace#143
• docs: document undocumented folders in scripts READMEs #216
• docs: add simulators folder to scripts README HowToGalaxy#68
• docs: fix cluster dataset path prose + document simulator folder HowToLens#72

Summary

All 12 real hygiene-refs defects fixed: 2 autoCTI_workspace/output casing references, 2 howtolens/dataset/cluster/simple re-points in the cluster simulator, and 8 missing README folder-list entries (each sourced from the folder's own README/docstrings). Notebook mirrors/twins regenerated per each repo's convention (autocti stays script-only per its release-time regen convention). Witness: hygiene refs re-scan of the branch dropped 18 → 5 findings.

Session Notes

• The 5 remaining findings (weak/*.py in tutorial_6_weak_lensing.py) plus imaging/features/scaling_relation in tutorial 3 were adjudicated scanner false positives — valid cross-repo references into autolens_workspace, deliberately untouched (same adjudication as the 2026-08-06 hygiene pass).
• Regeneration surfaced pre-existing notebook drift in 4 unrelated files (overview_3_statistical_methods.ipynb, aggregator/interferometer.ipynb, HowToLens tutorial_11_slam.ipynb / tutorial_9_model_fit.ipynb) — reverted, not swept in.
• Heart verdict at ship: STALE (release-rehearsal drift on library repos; no RED/YELLOW) — not a blocker for pending-release workspace prose PRs.
• All PRs are standalone (no upstream library PR); merge in any order.