Brain readability pass: README rewrite, ORGANISM Nerves currency, declutter (#237)

- README on the Mind/Heart pattern: organ opening, drive-it-in-plain-English,
  sequential 'How PyAutoBrain works' (conductor decides+acts, faculties
  advise, Brain -> Heart -> Hands, autonomy contract), CLI examples,
  pointers. The drifted hand copies (6-organ table, 5-of-18 verbs) are
  replaced by links to ORGANISM.md and AGENTS.md's generated table.
- ORGANISM.md records the Nerves rename (PyAutoConf -> PyAutoNerves,
  autoconf -> autonerves) instead of asserting the old name; same fix in
  docs/example.md and four skill-doc prose mentions
  (repo_cleanup/reference.md:128's stale owner mapping is left for the
  functional-leftovers follow-up).
- AI_POLICY.md + CONTRIBUTING.md move under .github/ (zero inbound refs;
  matches Mind #248 and Heart #151). 13 fully-merged remote branches deleted.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: 2 people

AI_POLICY.md .github/AI_POLICY.mdAI_POLICY.md renamed to .github/AI_POLICY.md

@@ -18,14 +18,14 @@ organs plan, build, test and release it, and you make every judgment call.
 | **Hands** | PyAutoHands | Builds and releases — packaging, tagging, notebook generation, PyPI via `release.yml`. A pure executor: runs no readiness checks and never re-derives a gate decision. |
 | **Memory** | PyAutoMemory | Long-term knowledge — *what the science says* (literature wikis, concepts, bibliographies). Operational history — *what the organism did* — lives in Mind (the `complete/` records, issues), not here. |
 | **Gut** | PyAutoGut | Owns the lifecycle of *condemned self-material* — stale branches, stashes, dead code/tests. Holds each as a durable, recoverable git ref through a transit window and **voids** it on a sweep. The storage mirror of Memory (retention ↔ release); the hygiene conductor drives it, as vitals reads Heart. |
-| **Nerves** | PyAutoConf | The configuration/serialization layer (`autoconf`) — layered config with overrides, the workspace↔library version handshake, `test_mode`, FITS/JSON I/O. Connects the organism's conventions to every library; the base layer the scientific libraries all import. The seventh organ. |
+| **Nerves** | PyAutoNerves | The configuration/serialization layer (`autonerves`) — layered config with overrides, the workspace↔library version handshake, `test_mode`, FITS/JSON I/O. Connects the organism's conventions to every library; the base layer the scientific libraries all import. The seventh organ. |
 
 *Hands* and *Build* name the **same organ** (PyAutoHands) throughout this
 document: the organ is the **Hands**, and *Build* is the call-chain step it
 performs. (The Hands repo was renamed PyAutoBuild → PyAutoHands; the *Build*
-call-chain shorthand and the `autohands` package/CLI keep their names.
-`PyAutoConf` likewise remains the Nerves repo's name, aligned with its
-`autoconf` package.)
+call-chain shorthand and the `autohands` package/CLI keep their names. The
+Nerves repo was likewise renamed PyAutoConf → PyAutoNerves, its package
+`autoconf` → `autonerves`.)
 
 The scientific libraries (PyAutoFit, PyAutoArray, PyAutoGalaxy, PyAutoLens) and
 the workspaces are **capabilities the organism uses, not organs**. The full
@@ -67,6 +67,6 @@ script), not as a repo. A new organ costs an `AGENTS.md`, a `CLAUDE.md` stub,
 install wiring, a body-map row and boundary prose — it must earn that by
 owning state or effects no existing organ can. Configuration/signalling is the
 one standing exception that already earned organ status: it is the **Nerves**
-(PyAutoConf), the base config/serialization layer every library imports — new
+(PyAutoNerves), the base config/serialization layer every library imports — new
 config surfaces belong there, not in a new organ. The human interaction layer
 is the command surface (`/route` + the verb commands), which is part of Brain.

CONTRIBUTING.md .github/CONTRIBUTING.mdCONTRIBUTING.md renamed to .github/CONTRIBUTING.md

@@ -6,37 +6,58 @@
 
 [![PyAutoScientist GitHub](https://img.shields.io/badge/%E2%9A%9B%EF%B8%8F%20PyAutoScientist-GitHub-181717?style=flat-square)](https://github.com/PyAutoLabs/PyAutoScientist) [![PyAutoScientist ReadTheDocs](https://img.shields.io/badge/%F0%9F%93%96%20PyAutoScientist-ReadTheDocs-8CA1AF?style=flat-square)](https://pyautoscientist.readthedocs.io)
 
-The reasoning layer of the PyAuto organism. Brain figures out *how* work
-gets done: it classifies incoming tasks, plans them, and routes them to
-specialist agents, delegating execution to the other organs. It holds no
-state, runs no health checks, and never releases anything itself.
-
-The organism is described once in [ORGANISM.md](ORGANISM.md). The short
-version:
-
-| Organ | Repo | Job |
-|-------|------|-----|
-| Mind | PyAutoMind | what to do — intent, priorities, workflow state |
-| Brain | PyAutoBrain (this repo) | how to do it — reasoning, planning, routing |
-| Heart | PyAutoHeart | is it healthy — the release-readiness verdict |
-| Hands | PyAutoHands | do it — packaging, tagging, PyPI releases |
-| Memory | PyAutoMemory | what we know — long-term scientific knowledge |
-| Gut | PyAutoGut | what we shed — condemned branches, stashes and dead code, held recoverably then voided |
-
-Agents live under `agents/` in two tiers: **conductors** (front doors a
-human drives; they decide and act) and **faculties** (read-only judgments
-the conductors consult). Humans mostly reach them through short slash
-commands — `/intake`, `/feature`, `/bug`, `/health`, `/route` — whose
-bodies live in `skills/`.
+**PyAutoBrain is the Brain of the PyAutoScientist** — the reasoning layer that
+turns intent into shipped software. It decides *how* work gets done: it
+classifies each task, plans it, and routes it to specialist agents — and it
+delegates everything else: it holds no state (the Mind's job), runs no health
+checks (the Heart's), and never releases anything itself (the Hands').
+
+You drive it in plain English, through short slash commands in a Claude Code
+chat: `/intake` to file an idea, `/start_dev` to begin a task, `/health` for a
+check-up — or just `/route <what you want>` and the Brain picks the right
+door. The full command surface (13 conductors + 5 faculties) is the generated
+table in [AGENTS.md](AGENTS.md).
+
+## How PyAutoBrain works
+
+1. **A task arrives.** Usually from the Mind's backlog — pick a task on the
+   [PyAutoMind dashboard](https://pyautolabs.github.io/PyAutoMind/) and paste
+   its `/start_dev` command — or free-form, via `/route` or any conductor's
+   own door.
+2. **A conductor takes it.** Conductors ([`agents/conductors/`](agents/conductors))
+   are the front doors a human drives; they decide *and* act: `intake`
+   conceives tasks, `feature`/`bug`/`refactor` plan development, `health`
+   runs the clinic, `release` drives a release, and so on.
+3. **Faculties advise.** Faculties ([`agents/faculties/`](agents/faculties))
+   are read-only opinions the conductors consult: `vitals` reads the Heart's
+   verdict, `sizing` estimates difficulty, `memory` recalls what the organism
+   knows, `review` judges a branch. A conductor never consults another
+   conductor — an opinion worth sharing becomes a faculty.
+4. **The organs execute.** Always in the same order — **Brain → Heart (gate)
+   → Hands (execute)**: work happens on task worktrees, ships as pull
+   requests behind the Heart's health verdict, and is packaged and released
+   by the Hands.
+5. **Autonomy is a contract.** How much a run may do without a human is
+   defined per task in [AUTONOMY.md](AUTONOMY.md) — a safe-capped task may
+   carry itself to an open pull request; merging and releasing always stay
+   human.
+
+## CLI examples
+
+The same agents are runnable directly — every slash command is a verb of one
+CLI, which runs straight from this checkout (no pip install):
 
 ```bash
-bin/pyauto-brain help        # list the agents
-bin/pyauto-brain vitals      # one health tick + the dashboard card
-bash bin/install.sh          # symlink every organ's skills into ~/.claude
+bin/pyauto-brain help                      # list every conductor and faculty
+bin/pyauto-brain route "fix the failing lens smoke test"   # plain English in
+bin/pyauto-brain vitals                    # read the Heart's readiness verdict
+bash bin/install.sh                        # symlink every organ's skills into ~/.claude
 ```
 
-Runs straight from its checkout — no pip install. Agent contracts and the
-organ boundary are in [AGENTS.md](AGENTS.md); how much a run may do without
-a human is the autonomy contract, [AUTONOMY.md](AUTONOMY.md). The full
-organism documentation — including how to fork and run your own — is at
-<https://pyautoscientist.readthedocs.io> (source: `docs/`).
+The seven organs the Brain coordinates — Mind (intent), Brain (reasoning),
+Heart (health), Hands (release), Memory (knowledge), Gut (shedding), Nerves
+(configuration) — are defined once in [ORGANISM.md](ORGANISM.md), which this
+repo hosts. Agent contracts and the generated command table are in
+[AGENTS.md](AGENTS.md). The full organism documentation — including how to
+fork it and lead your own — is at <https://pyautoscientist.readthedocs.io>,
+whose source lives here in [`docs/`](docs).

ORGANISM.md

@@ -10,7 +10,7 @@ replaces every name below with your own.
 
 The live `repos.yaml` declares ~25 repos. The load-bearing categories:
 
-- **Libraries:** PyAutoConf (shared config), PyAutoFit (Bayesian
+- **Libraries:** PyAutoNerves (shared config), PyAutoFit (Bayesian
   inference), PyAutoArray (data structures), PyAutoGalaxy (galaxy
   modelling), PyAutoLens (strong lensing), PyAutoReduce (data reduction) —
   a dependency chain released to PyPI nightly when there is new activity.

README.md

@@ -54,7 +54,7 @@ this covers residue when that flow is skipped); the start_dev branch survey
 
 ## Scope
 
-**Always swept:** library canonical checkouts under `$PYAUTO_MAIN` (PyAutoConf,
+**Always swept:** library canonical checkouts under `$PYAUTO_MAIN` (PyAutoNerves,
 PyAutoFit, PyAutoArray, PyAutoGalaxy, PyAutoLens, PyAutoHands); workspaces incl.
 `_test`/`_developer` variants (autofit/autogalaxy/autolens families, HowToLens);
 and worktree roots under `$PYAUTO_WT_ROOT`.

docs/example.md

@@ -19,7 +19,7 @@ Given a GitHub URL, before writing any adapter code:
    example (e.g. nessai routes users to a `nessai-bilby` plugin), go to the
    docs site and examples dir — never guess an API from the package name.
 2. **Dependency-compatibility check** against the installed stack *before*
-   `pip install`: Python floor, JAX pin overlap with PyAutoConf's `[jax]`
+   `pip install`: Python floor, JAX pin overlap with PyAutoNerves's `[jax]`
    floor/ceiling, and heavyweight extras (a PyTorch-core sampler like nessai
    brings CUDA-pinning risk beside the JAX stack). Under-declared floors are
    real (the nufftax lesson) — check what the code imports, not just

skills/repo_cleanup/SKILL.md

@@ -1,6 +1,6 @@
 # Ship Library: Gate, Test, PR
 
-Ship source-library changes (PyAutoConf, PyAutoFit, PyAutoArray, PyAutoGalaxy,
+Ship source-library changes (PyAutoNerves, PyAutoFit, PyAutoArray, PyAutoGalaxy,
 PyAutoLens) for every library repo touched by the task. This is
 **feature-development** work — the commit/push/feature-PR is the dev workflow's
 own execution, gated by Heart. It is **not** a Build task (Build is

skills/sampler_pipeline/reference.md

@@ -1,6 +1,6 @@
 # Start Library: Set Up Library Development
 
-Set up the development environment for **library source-code** work (PyAutoConf,
+Set up the development environment for **library source-code** work (PyAutoNerves,
 PyAutoFit, PyAutoArray, PyAutoGalaxy, PyAutoLens). Assumes `/start_dev` already
 registered the task in `PyAutoMind/active.md`.