docs: three-ways-to-learn guide + prune stale API-doc references

[Jammy2211]

Summary

Phase C + Phase A of the release-docs polish (#592).

• Phase C — Three Ways to Learn: adds a "Three Ways to Learn PyAutoLens" subsection (manual navigation / AI chat assistant / fully agentic AI) to overview_2_new_user_guide.md, and reframes autolens_assistant from "experimental / not recommended" to a first-class option in README.md + docs/index.md.
• Phase A — API-doc cleanup: prunes docs/api/*.rst autosummary entries for removed API — the OO plotting subsystem (MatPlot2D/Cmap/*Scatter, replaced by the functional plot API), PySwarms*, PointDict, SetupAdapt→AdaptImages, OverSampling→OverSampler, and dead linear Chameleon entries (kept correctly under light_and_mass_profiles). Re-audit reports zero broken/missing/duplicate references.

The positive functional-API plot.rst rewrite is filed as a follow-up (PyAutoMind docs/autolens/plot_rst_functional_api_rewrite.md).

Validation checklist (--auto, supervised)

• Tests: n/a — zero Python source changed (only docs/*.rst, docs/*.md, README.md); no public-API/downstream surface.
• Smoke: n/a — no downstream script surface in this repo's diff.
• Review: CLEAN — review-faculty surface; re-audit confirms every autosummary reference resolves against the installed stack; CRLF preserved (byte-safe edits).
• Heart: YELLOW — reason set human-acknowledged at ship (5 chronic organism reasons: stale workspace-validation, 58 parked scripts, assistant pin-behind, 3 timing regressions, 10d-old Mind PR; none from this change, none RED).

Autonomous run ended at PR-open; merge stays human. Library-first gate: merge this + PyAutoGalaxy before the autolens_workspace PR.

Closes-part-of #592.

🤖 Generated with Claude Code