PyAutoScientist Phase 2: RTD docs, adoption guide, CONTRIBUTING, hub card

[Jammy2211]

Overview

Phase 2 of the PyAutoScientist generalisation (Phase 1 = #65, merged 2026-07-10): the pyautoscientist ReadTheDocs, sourced from PyAutoBrain/docs/, plus the adoption guide, per-organ CONTRIBUTING disclaimers, and the hub card. All new prose — it documents the skills, it never rewrites them. Scope per PyAutoMind/issued/pyautoscientist_generalisation.md items 5–7 and the settled direction (§4/§8 of the companion assessment — config-diff fork, one live organism, lensing stays as the labelled worked example).

Plan

• RTD skeleton in PyAutoBrain/docs/ (Sphinx + Furo + MyST markdown), published as the pyautoscientist RTD project: concepts (organism, call chain, conductors/faculties, growth rule — sourced from ORGANISM.md, not duplicated), per-organ reference, the category contract (what each satellite kind is for and what the organism expects of it), the adoption guide written against the fork model (fork → replace config surfaces → body map → repos_sync --write → go; prerequisites stated plainly as what PyAutoScientist is), and the worked example (the live lensing instance, labelled).
• Docs CI + theming, matching the pattern shipped for Fit/Galaxy/Lens (2026-07-10): thin docs.yml caller → Heart's reusable docs-build.yml; docs/sphinx_warning_baseline.txt = 0 (fresh tree, strict); shared docs/_static/pyauto.css brand layer; Furo accent pair for pyautoscientist. Heart's reusable workflow gains an additive docs-only case (PyAutoBrain has no pip package — install docs/requirements.txt instead of ./repo[optional,docs]); existing callers unchanged.
• CONTRIBUTING + stability disclaimer in each organ: living reference implementation, main moves fast, copy/fork-and-pull, no compatibility promises. Canonical text in PyAutoBrain; short pointer versions in Mind/Heart/Memory/Build.
• README RTD link — one line added to each organ README (the "once live" hook left by Phase 1), pointing at https://pyautoscientist.readthedocs.io.
• Hub card on pyautolabs.github.io: a PyAutoScientist section (mini-card style) linking the RTD + PyAutoBrain, plus a footer link.
• Human leg (post-merge): import the pyautoscientist project on readthedocs.org pointing at PyAutoLabs/PyAutoBrain.

Detailed implementation plan

Affected Repositories

• PyAutoBrain (primary) — docs/ tree, .readthedocs.yaml, docs.yml caller, CONTRIBUTING.md, README line
• PyAutoHeart — docs-build.yml additive docs-only case, CONTRIBUTING.md, README line
• PyAutoMind — CONTRIBUTING.md, README line
• PyAutoMemory — CONTRIBUTING.md, README line
• PyAutoBuild — CONTRIBUTING.md, README line
• pyautolabs.github.io — PyAutoScientist section + footer link

Branch Survey (2026-07-10)

All six repos on clean main (PyAutoMemory: unrelated dirty reading-queue.md, untouched). No worktree-claim conflicts.

Suggested branch: feature/pyautoscientist-phase2 (worktree ~/Code/PyAutoLabs-wt/pyautoscientist-phase2/); 6 PRs.

Docs page tree (all MyST markdown, new prose)

docs/
├── conf.py                  # Furo + myst_parser, pyautoscientist accents
├── requirements.txt         # sphinx, furo, myst-parser
├── sphinx_warning_baseline.txt   # 0
├── _static/pyauto.css       # shared brand layer (identical file)
├── index.md                 # what PyAutoScientist is; who it's for; honest prerequisites
├── concepts/organism.md     # organs, boundaries, call chain (links ORGANISM.md)
├── concepts/agents.md       # conductors vs faculties, consult DAG, growth rule
├── concepts/workflow.md     # prompt → issue → worktree → ship; autonomy contract
├── organs/{mind,brain,heart,build,memory}.md   # per-organ reference
├── satellites.md            # the category contract
├── adoption/guide.md        # the config-diff fork walkthrough
├── adoption/config_surfaces.md  # declared surfaces + tenant firewall
└── example.md               # the live lensing instance, labelled worked example

Acceptance (phase 1–2 acceptance from the prompt)

• Zero diffs to skill bodies, AGENTS.md files, hooks, or organ runtime code (Heart's reusable docs workflow extension is additive CI config, disclosed).
• repos_sync.py --check green incl. tenant firewall (docs conf.py carries no instance facts or gets a justified allowlist entry).
• Heart/Build/Brain suites green; one PR per repo, normal ship gate; supervised.
• A stranger reading the RTD can explain the organism and knows exactly what forking it entails.

Original Prompt

Anchor: PyAutoMind/issued/pyautoscientist_generalisation.md (Phase 2 = items 5–7; full text on #65).

🤖 Generated with Claude Code

[Jammy2211]

Phase 2 shipped — 6 PRs open:

Repo	PR	Contents
PyAutoBrain	#70	docs/ RTD source (13 pages, Sphinx+Furo+MyST, 0-warning baseline), docs.yml CI caller, .readthedocs.yaml, canonical CONTRIBUTING, README RTD link
PyAutoHeart	#50	docs-build.yml docs-only mode (additive), CONTRIBUTING, README link
PyAutoMind	#45	CONTRIBUTING, README link
PyAutoMemory	#18	CONTRIBUTING, README link
PyAutoBuild	#132	CONTRIBUTING, README link
pyautolabs.github.io	#2	PyAutoScientist section + footer link

Validation: Sphinx build clean (0 warnings = strict baseline); suites 8/244/78; repos_sync --check green incl. tenant firewall; Heart YELLOW (same 6-reason set as the Phase 1 ack) acknowledged in-session.

Merge order: PyAutoHeart#50 first — PyAutoBrain#70's Docs check calls the reusable workflow @main and needs the new pyautoscientist case; re-run the check after Heart merges. Brain also has the parallel disjoint claim (nightly-loud-failure #67) — no file overlap.

Human leg after merge: import the pyautoscientist project on readthedocs.org → PyAutoLabs/PyAutoBrain. All placed links (https://pyautoscientist.readthedocs.io) resolve once it builds.

[Jammy2211]

All 6 Phase 2 PRs merged 2026-07-10 (Heart#50 first; Brain#70's Docs check re-run through the new docs-only mode → green — end-to-end proof of the reusable-workflow extension). repos_sync --check green on merged mains. Remaining human leg: RTD import of pyautoscientist → PyAutoLabs/PyAutoBrain (in progress — PyAutoBrain needs adding to the Read the Docs GitHub App's repository grant, or manual import + webhook). Hub deploys from main via Pages. Phase 3 stays demand-gated in PyAutoMind/issued/pyautoscientist_generalisation.md. Closing.