docs: reference-assistant audit — adaptive assistant mode, README/AGENTS cleanup, template notes

[Jammy2211]

Closes #33. Phase 1 of the reference-assistant audit: the audit report (below), the interaction-mode merge, README/AGENTS cleanup, and template-boundary notes. Skill-stub completion is deferred to a second PR.

Audit report

What was inspected

README.md, AGENTS.md, all four modes/*.md, skills/README.md + skills/_style.md, the wiki core/literature/project split docs, wiki/project/_profile_template.md, start-new-project/contribute-upstream boundaries, llms.txt, .gitignore sentinels, and a repo-wide sweep of every mode reference.

What changed

• Mode model (the one design change): Assistant and Agent merge into a single adaptive Assistant mode; Teacher stays distinct. modes/assistant.md gains "The autonomy dial": conversational by default (act with the user, check in before big decisions), scaling to phased, checkpointed execution with wiki/project/ state only when the user asks for autonomy. The agent mode name is removed entirely — no legacy alias: modes/agent.md is deleted and the mode vocabulary is exactly teacher | assistant. All reference sites reconciled: AGENTS.md Modes + selection order, README Modes + example prompt 3, _profile_template.md, .gitignore comment, skills/_style.md mode-invariance rule.
• README: two-mode explanation with an explicit "just say how hands-on you want to be" framing; example 3 reworked as asking assistant mode for autonomy; typo fix ("preparaton").
• Maintainer notes (assistant-as-template): modes/maintainer.md gains a generic-infrastructure vs PyAutoLens-specific vs mixed mapping — the seam a future assistant-cloning workflow (filed separately in the Mind as the Brain Clone/Mitosis Agent) cuts along.
• Skills index: one-line maturity legend (complete-unless-(stub)).

What was deliberately not changed

• Safety invariants — audited, found clear and non-contradictory; untouched.
• AGENTS.md structure — at 199 lines it is concise and well-ordered (session start → invariants → layers → modes → skills → sources → cadence → conventions); only the Modes section changed.
• skills/README.md index — already cleanly split into mature sections and a "Pending — stubbed" section with per-entry (stub) labels and a queue; no stub content written (phase 2).
• Wiki scientific content, skill names, output//sources/ machinery, hooks.
• The three README examples — they remain the right three, now mapping onto teacher / conversational assistant / assistant-with-autonomy.

Breaking-change note

A .mode file or profile.md interaction-mode entry saying agent is no longer recognised — users write assistant and state their autonomy preference in prose. Existing clones are unaffected until they update; there is no code path, only instruction text.

Validation

• make validate-literature-citations — passes (re-run after every commit).
• autoassistant/audit_skill_apis.py symbol audit — 55 files, 110 symbols, 0 missing/broken.
• --check-version fails on the pre-existing stack skew (assistant pinned 2026.5.29.4 vs installed 2026.7.6.649, already flagged by Heart) — unrelated to this PR, which touches no API content.
• Relative-link check over all edited files — clean; repo-wide greps confirm no dangling modes/agent.md links and no stale "three modes"/"agent mode"/alias references remain.

Most important follow-up work

1. Phase 2: upgrade one high-value skill stub to a full recipe (best first candidate: al_subhalo_detect — README example 3 exercises it).
2. Refresh the version pin / regenerate wiki/core against the installed 2026.7.6 stack (existing Heart finding).
3. The Clone/Mitosis Agent design prompt (PyAutoMind/feature/pyautobrain/clone_mitosis_agent.md) builds on the template-boundary notes added here.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.