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

.gitignore

@@ -47,8 +47,8 @@ papers/
 # no newcomer-mode defaults). See AGENTS.md and modes/maintainer.md.
 .maintainer
 
-# Interaction-mode override — optional per-clone file containing one of
-# `teacher` | `assistant` | `agent`. See AGENTS.md "Modes". `.maintainer` outranks it.
+# Interaction-mode override — optional per-clone file containing `teacher` or
+# `assistant`. See AGENTS.md "Modes". `.maintainer` outranks it.
 .mode
 
 # Claude Code agent worktrees — ephemeral, machine-local.

AGENTS.md

@@ -88,13 +88,15 @@ the profile is older than ~10 sessions, ask whether anything changed.
 
 ## Modes
 
-Interaction presets for one assistant (not a multi-agent system) — how much it teaches,
-plans, and acts, not which workflows exist:
+Interaction presets for one assistant (not a multi-agent system) — how much it teaches and
+how it paces the work, not which workflows exist:
 
 - **Teacher** — *learn*: explain, step through, point to examples.
-- **Assistant** — *do*: concise; write/edit/run; ask only when correctness/setup needs it.
-- **Agent** — *run*: clarify, plan in phases, execute with checkpoints — proactive but not
-  silent; state in `wiki/project/`.
+- **Assistant** — *do*: adapts planning, conversation and autonomy to the request. Default is
+  conversational — concise; write/edit/run; ask only when correctness/setup needs it. When
+  the user asks for a long or multi-session run, scale up: clarify the goal, plan in phases,
+  execute with checkpoints — proactive but not silent; state in `wiki/project/`. The dial is
+  in [`modes/assistant.md`](./modes/assistant.md) "The autonomy dial".
 
 Select (first match): explicit instruction → `.mode` file → `profile.md` "Interaction mode" →
 else **infer from the opening request** (fall back to **assistant**); `.maintainer` outranks

README.md

@@ -60,15 +60,20 @@ you provide the relevant files and outputs.
 
 ## Modes
 
-The assistant works in three modes, and you never have to choose one — it **infers the mode
+The assistant works in two modes, and you never have to choose one — it **infers the mode
 from your first message and tells you which it picked** (e.g. *"Mode: teacher — I'll explain
 as we go."*). If it guesses wrong, just say so. To set the mode yourself, start your message
 with it (the examples below do exactly that); to make a choice permanent, drop a `.mode` file
-in the repo containing `teacher`, `assistant`, or `agent`.
+in the repo containing `teacher` or `assistant`.
 
 - **Teacher** — *learn the workflow.* `Teacher mode: I'm new to PyAutoLens — how do I model this image?`
 - **Assistant** — *do the workflow.* `Assistant mode: set up a project for this dataset and write the first script.`
-- **Agent** — *run the project.* `Agent mode: model this lens end-to-end and track progress across sessions.`
+
+Assistant mode adapts how much it plans, talks, and acts to your request. By default it works
+conversationally — doing each step with you and checking in before big decisions. Ask for
+autonomy (*"model this lens end-to-end and track progress across sessions"*) and it plans in
+phases and runs with checkpoints instead. There is no separate mode to manage: just say how
+hands-on you want to be.
 
 ## Example Prompt 1 using Teacher Mode: Simulate Euclid imaging of a simple strong lens, fit it and then model it
 
@@ -100,16 +105,16 @@ with concise output rather than a step-by-step tutorial.
 ```
 Assistant mode.
 
-Model the JWST imaging in dataset/imaging/cosmos_web_ring: perform data preparaton steps, 
+Model the JWST imaging in dataset/imaging/cosmos_web_ring: perform data preparation steps, 
 set up a sensible lens light and mass model with a pixelized source reconstruction, run 
 the fit, and show me the reconstructed source and the fit residuals.
 ```
 
-## Example Prompt 3 using Agent Mode: Detect a Dark Matter Subhalo in SLACS0946+1006 via Bayesian Model Comparison
+## Example Prompt 3 asking Assistant Mode for Autonomy: Detect a Dark Matter Subhalo in SLACS0946+1006 via Bayesian Model Comparison
 
 For users already comfortable with strong lens modelling who want to see
-how far the assistant can be pushed in **agent mode**. SLACS0946+1006 
-has a famous subhalo  detection that is argued to be unusually concentrated; 
+how far the assistant can be pushed when **asked to run autonomously**. SLACS0946+1006
+has a famous subhalo detection that is argued to be unusually concentrated; 
 this prompt asks the assistant to reproduce that detection and quantify the 
 concentration via Bayesian model comparison.
 
@@ -119,7 +124,8 @@ if needed, walk you through setting the analysis up on a High Performance
 Computer (HPC) you have access to.
 
 ```
-Agent mode.
+Assistant mode — run this autonomously, planning in phases and checkpointing
+with me at the big scientific decisions.
 
 The strong lens SLACS0946+1006 famously has a dark matter subhalo
 detection that many argue is unusually concentrated. I'd like to analyse

modes/assistant.md

@@ -1,8 +1,8 @@
 # Assistant mode (default)
 
-The baseline posture, for users who want work *done*. This is the constitution's default
-behavior and carries no deltas beyond `AGENTS.md` itself — the file exists so mode resolution
-("read `modes/<mode>.md`") is uniform across all three modes.
+The baseline posture, for users who want work *done*. The default is conversational; when
+the user asks for autonomy, the same mode scales its planning and checkpointing up (see
+"The autonomy dial" below) — there is no separate mode to switch into.
 
 ## Posture
 
@@ -13,14 +13,37 @@ behavior and carries no deltas beyond `AGENTS.md` itself — the file exists so
 - Concision applies to the conversation, not the saved artefact: Python docstrings retain the
   full workspace-style detail required for publication-quality, reusable analysis code.
 
+## The autonomy dial
+
+Stay at the conversational posture above unless the user asks for a long, multi-step or
+multi-session task to be carried through rather than answered turn-by-turn ("end-to-end",
+"run this over several sessions", "hands-off", "autonomously"). Then scale up:
+
+- Clarify the science goal and ask the essential questions up front.
+- Build a phased plan; execute step by step; summarise after each phase.
+- Check in at major scientific decision points; state assumptions explicitly rather than make
+  silent ones. **Autonomy is proactive, but not silent.**
+- Maintain project state in `wiki/project/` — dated `YYYY-MM-DD-<slug>.md` entries plus
+  `profile.md`, the journal that already exists. Do **not** create parallel root-level state
+  files (`agent_plan.md`, `project_log.md`, …).
+
+Autonomy never loosens the constitution: the real-data gate and the source-edit boundary
+apply unchanged, and this remains one conversational assistant, not a swarm of subagents.
+
 ## What stays the same
 
 - All `AGENTS.md` safety invariants and the source-edit boundary apply.
 - Pedagogical depth still follows `skills/_style.md` "Adaptive depth".
-- Saved Python follows `skills/_style.md` "Generated script style", including scientific and
-  inference framing, consequential assumptions, reproducibility context, and source citations.
+- Saved Python follows `skills/_style.md` "Generated script style" — scientific and
+  inference framing, consequential assumptions, reproducibility context, and source
+  citations — at every autonomy level.
 
 ## What triggers inference
 
-"Set up a project for this dataset", "Write the first modelling script", "Debug this error",
-"Use the standard imaging pipeline", "Inspect these results and tell me what to try next."
+Conversational: "Set up a project for this dataset", "Write the first modelling script",
+"Debug this error", "Use the standard imaging pipeline", "Inspect these results and tell me
+what to try next."
+
+Autonomy: "Model this lens end-to-end", "Plan and execute the full SLaM analysis", "Run this
+project over several sessions and track progress", "Analyse this sample and summarise the
+results."

modes/maintainer.md

@@ -54,6 +54,31 @@ Ordering matters at release: PyAutoBuild regenerates + commits the API baseline
 calling this workflow, so `--check-version` compares the new stack against an already-updated
 baseline. When you change the rules, edit them here only; never copy a rule into PyAutoBuild.
 
+## Assistant-as-template: generic vs PyAutoLens-specific
+
+This repo is the reference implementation future PyAuto domain assistants (e.g.
+`autofit_assistant`, `autogalaxy_assistant`) will be modelled on. When maintaining it, keep
+this boundary in mind — it is the seam a future cloning workflow will cut along. Do not
+generalise anything pre-emptively; just avoid entangling the two sides.
+
+**Generic assistant infrastructure** (clones to any domain assistant near-verbatim):
+`AGENTS.md`'s skeleton (session start, safety invariants, three-layer model, mode
+selection, source-of-truth resolution, commit cadence), the Teacher/Assistant mode model
+and `modes/` machinery (`.mode`, `.maintainer` sentinels), the skills framework
+(`_style.md`, `_bootstrap_skill.md`, the README index conventions), the
+`core`/`literature`/`project` wiki split and its read-only/update rules, the science-project
+lifecycle (`start-new-project`, `contribute-upstream`), `sources.yaml` + the source
+registry pattern, the API gate (`autoassistant/audit_skill_apis.py` + wiki-currency
+workflow), and the profile template.
+
+**PyAutoLens-specific content** (regenerated per domain, never copied blind): every
+`al_*` skill body, `wiki/core/` reference pages, the entire `wiki/literature/` sub-wiki,
+bundled `dataset/` examples, the README's science framing and three example prompts, the
+standard-imports convention, and `hpc/` templates tuned to lensing runtimes.
+
+**Mixed** (structure generic, values domain-specific): `llms.txt` read-order,
+`config/`, the maintainer smoke tests below.
+
 ## Chat-surface compatibility smoke test
 
 Run these checks after documentation changes are available on the public GitHub repository. Do

skills/README.md

@@ -24,6 +24,10 @@ configured) via symlinks; the canonical files live here.
 
 ## Index
 
+Every skill below is a **complete recipe** unless marked `(stub)` — the stubs are gathered
+under "Pending — stubbed" at the end, with a queue of catalogued-but-unstubbed topics after
+them.
+
 ### Meta
 
 - [`_style.md`](./_style.md) — writing guide every skill is authored against. Read first

skills/_style.md

@@ -74,8 +74,8 @@ markdown cell and the code between blocks becomes a code cell.
 
 Two rules.
 
-The level of detail in a saved script is **mode-invariant**. Teacher, assistant, and agent
-modes may change the pacing and depth of the surrounding conversation, but they must not
+The level of detail in a saved script is **mode-invariant**. Teacher and assistant modes —
+at any autonomy level — may change the pacing and depth of the surrounding conversation, but they must not
 change the completeness of the script artefact. Write docstrings as if the script may become
 part of the open-source repository accompanying a paper: preserve the scientific motivation,
 what is inferred and how, consequential assumptions and configuration choices, enough context

wiki/project/_profile_template.md

@@ -38,12 +38,13 @@ _unrecorded_
 
 ## Interaction mode
 
-Durable preference for how the assistant should interact: `teacher` (learn the workflow),
-`assistant` (do the workflow), or `agent` (run the project). Leave unrecorded to let the
-assistant infer the mode from each opening request. See `AGENTS.md` "Modes". Examples:
+Durable preference for how the assistant should interact: `teacher` (learn the workflow) or
+`assistant` (do the workflow — note a preferred autonomy level in prose if it's durable).
+Leave unrecorded to let the assistant infer the mode from each opening request. See
+`AGENTS.md` "Modes". Examples:
 
 - "teacher — workshop attendee, wants the science explained."
-- "agent — running a multi-session subhalo project."
+- "assistant — prefers autonomous multi-session runs (subhalo project)."
 
 _unrecorded_