docs: consolidate agent instructions into canonical AGENTS.md

AGENTS.md

@@ -1,66 +1,86 @@
 # PyAutoConf — Agent Instructions
 
-**PyAutoConf** is the configuration management library for the PyAuto ecosystem. It handles object serialization/deserialization, JSON-based priors, and configuration generation.
+Canonical, agent-agnostic instructions for this repo. `CLAUDE.md` imports this
+file; any tool that does not process `@`-imports should read this directly.
 
-## Setup
+## What this repo is
 
-```bash
-pip install -e ".[dev]"
-```
+**PyAutoConf** (package `autoconf`) is the configuration, serialization, and
+I/O foundation of the PyAuto ecosystem: layered config with overrides,
+dict/JSON/CSV serialization, FITS I/O, JSON-based priors, and the shared
+`jax_wrapper` / `test_mode` utilities.
+
+Dependency direction: autoconf is the **base layer**. It does **not** import
+`autofit`, `autoarray`, `autogalaxy`, or `autolens`. All four of those depend
+on autoconf, so any public-API change here ripples downstream.
+
+## Related repos
 
-## Running Tests
+- **Source siblings (downstream):** PyAutoFit, PyAutoArray, PyAutoGalaxy,
+  PyAutoLens — all depend on autoconf.
+- No `_workspace`, `_workspace_test`, or HowTo companion repo.
+- No `docs/` / RTD site — the package source and `test_autoconf/` are the
+  authoritative reference.
+
+## Quick commands
 
 ```bash
-python -m pytest test_autoconf/
+pip install -e ".[dev]"              # install with dev/test extras
+python -m pytest test_autoconf/      # full test suite
+python -m pytest test_autoconf/tools/test_decorators.py   # one focused test
+black autoconf/                      # formatter (advisory — not gated)
 ```
 
-### Sandboxed / Codex runs
+In a sandboxed / restricted environment, point numba and matplotlib at
+writable caches:
 
 ```bash
 NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python -m pytest test_autoconf/
 ```
 
-## Key Architecture
+## CI / definition of green
+
+PRs must pass `pytest --cov` on the CI matrix (Python 3.12 **and** 3.13). There
+is no black/ruff/flake8 gate — formatting is advisory. (`requires-python` in
+`pyproject.toml` is `>=3.9`.)
 
-- `autoconf/conf.py` — Core configuration system
-- `autoconf/dictable.py` — Dictionary/serialization support for YAML
-- `autoconf/fitsable.py` — FITS file handling
-- `autoconf/json_prior/` — JSON-based configuration priors
-- `autoconf/tools/` — Utility decorators and helpers
-- `autoconf/mock/` — Mock objects for testing
+## Public API
 
-## Key Rules
+The public surface is defined authoritatively in `autoconf/__init__.py` — read
+it rather than trusting a hand-maintained list. Canonical import:
+
+```python
+from autoconf import conf
+```
 
-- All files must use Unix line endings (LF)
-- If changing public API, note it in your PR description — all downstream PyAuto packages depend on this
+Key surfaces: `Config` / `conf.instance`, `output_to_json` / `from_json`
+(`dictable.py`), `output_to_fits` / `ndarray_via_fits_from` (`fitsable.py`).
 
-## Working on Issues
+## Key rules / footguns
+
+- All files use Unix line endings (LF, `\n`) — never `\r\n`.
+- This is the base config/IO layer: a public-API change here can break
+  PyAutoFit, PyAutoArray, PyAutoGalaxy, and PyAutoLens. Flag it loudly.
+- YAML dict keys are lowercased on load (`muJy` → `mujy`); keep config keys and
+  any matching Python registries snake_case-lowercase.
+
+## Working on issues
 
 1. Read the issue description and any linked plan.
-2. Identify affected files and write your changes.
-3. Run the full test suite: `python -m pytest test_autoconf/`
-4. Ensure all tests pass before opening a PR.
-5. If changing public API, clearly document what changed — PyAutoFit, PyAutoArray, PyAutoGalaxy, and PyAutoLens all depend on this package.
-## Never rewrite history
-
-NEVER perform these operations on any repo with a remote:
-
-- `git init` in a directory already tracked by git
-- `rm -rf .git && git init`
-- Commit with subject "Initial commit", "Fresh start", "Start fresh", "Reset
-  for AI workflow", or any equivalent message on a branch with a remote
-- `git push --force` to `main` (or any branch tracked as `origin/HEAD`)
-- `git filter-repo` / `git filter-branch` on shared branches
-- `git rebase -i` rewriting commits already pushed to a shared branch
-
-If the working tree needs a clean state, the **only** correct sequence is:
-
-    git fetch origin
-    git reset --hard origin/main
-    git clean -fd
-
-This applies equally to humans, local Claude Code, cloud Claude agents, Codex,
-and any other agent. The "Initial commit — fresh start for AI workflow" pattern
-that appeared independently on origin and local for three workspace repos is
-exactly what this rule prevents — it costs ~40 commits of redundant local work
-every time it happens.
+2. Identify affected files and make the change.
+3. Run the full suite: `python -m pytest test_autoconf/`.
+4. If you changed public API, say so explicitly — PyAutoFit, PyAutoArray,
+   PyAutoGalaxy, and PyAutoLens all depend on this package and may need updates.
+5. Ensure all tests pass before opening a PR.
+
+## Clean state
+
+Never rewrite history on a repo with a remote (no `git init` over a tracked
+tree, no force-push to `main`, no rebasing pushed shared branches). To reset a
+dirty tree the only correct sequence is:
+
+```bash
+git fetch origin
+git reset --hard origin/main
+git clean -fd
+```

CLAUDE.md

@@ -1,65 +1,5 @@
-# PyAutoConf
-
-**PyAutoConf** is the configuration management library for the PyAuto ecosystem. It handles object serialization/deserialization via YAML, JSON-based priors and configuration generation, and provides utility tools for scientific Python applications.
-
-- Package name: `autoconf`
-- Requires Python >= 3.12
-
-## Repository Structure
-
-- `autoconf/` — Main package
-  - `conf.py` — Core configuration system
-  - `dictable.py` — Dictionary/serialization support
-  - `fitsable.py` — FITS file handling
-  - `json_prior/` — JSON-based configuration priors
-  - `tools/` — Utility decorators and helpers
-  - `mock/` — Mock objects for testing
-- `test_autoconf/` — Test suite (pytest)
-
-## Commands
-
-### Install
-```bash
-pip install -e ".[dev]"
-```
-
-### Run Tests
-```bash
-python -m pytest test_autoconf/
-python -m pytest test_autoconf/ -s
-```
-
-### Codex / sandboxed runs
-
-When running Python from Codex or any restricted environment, set writable cache directories:
-
-```bash
-NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python -m pytest test_autoconf/
-```
-
-## Line Endings — Always Unix (LF)
-
-All files **must use Unix line endings (LF, `\n`)**. Never write `\r\n` line endings.
-## Never rewrite history
-
-NEVER perform these operations on any repo with a remote:
-
-- `git init` in a directory already tracked by git
-- `rm -rf .git && git init`
-- Commit with subject "Initial commit", "Fresh start", "Start fresh", "Reset
-  for AI workflow", or any equivalent message on a branch with a remote
-- `git push --force` to `main` (or any branch tracked as `origin/HEAD`)
-- `git filter-repo` / `git filter-branch` on shared branches
-- `git rebase -i` rewriting commits already pushed to a shared branch
-
-If the working tree needs a clean state, the **only** correct sequence is:
-
-    git fetch origin
-    git reset --hard origin/main
-    git clean -fd
-
-This applies equally to humans, local Claude Code, cloud Claude agents, Codex,
-and any other agent. The "Initial commit — fresh start for AI workflow" pattern
-that appeared independently on origin and local for three workspace repos is
-exactly what this rule prevents — it costs ~40 commits of redundant local work
-every time it happens.
+# PyAutoConf — agent instructions
+The canonical, agent-agnostic instructions live in `AGENTS.md`. Claude Code loads them
+via the import below; if your tool does not process `@`-imports, open `AGENTS.md` in
+this directory and read it directly.
+@AGENTS.md

README.md

@@ -1 +1,56 @@
 # PyAutoConf
+
+**PyAutoConf** (package `autoconf`) is the configuration, serialization, and
+I/O foundation of the [PyAuto](https://github.com/PyAutoLabs) ecosystem. It
+provides a layered configuration system with workspace overrides, dict / JSON /
+CSV serialization of arbitrary objects, and FITS I/O.
+
+`PyAutoFit`, `PyAutoArray`, `PyAutoGalaxy`, and `PyAutoLens` all depend on
+autoconf: it supplies their packaged default config, the object-serialization
+used to persist models and results, and shared utilities (`test_mode`,
+`jax_wrapper`). Centralising these here keeps a single, consistent config and
+I/O layer beneath every library.
+
+## Install
+
+```bash
+pip install autoconf
+```
+
+## Examples
+
+Layered config — read a directory of YAML into a queryable `Config`:
+
+```python
+from autoconf.conf import Config
+
+config = Config("path/to/config")          # directory of YAML files
+value = config["general"]["model"]["section"]["value"]
+```
+
+JSON serialization — round-trip arbitrary Python objects:
+
+```python
+from autoconf.dictable import output_to_json, from_json
+
+data = {"sersic_index": 4.0, "centre": [0.0, 0.0]}
+output_to_json(data, "model.json")
+restored = from_json("model.json")         # == data
+```
+
+FITS I/O — write and read a NumPy array:
+
+```python
+import numpy as np
+from autoconf.fitsable import output_to_fits, ndarray_via_fits_from
+
+arr = np.arange(12.0).reshape(3, 4)
+output_to_fits(values=arr, file_path="demo.fits", overwrite=True)
+loaded = ndarray_via_fits_from(file_path="demo.fits", hdu=0)   # np.allclose(arr, loaded)
+```
+
+## Links
+
+- Source & tests: [`autoconf/`](autoconf), [`test_autoconf/`](test_autoconf)
+- Agent/contributor instructions: [`AGENTS.md`](AGENTS.md)
+- Ecosystem: [PyAutoLabs on GitHub](https://github.com/PyAutoLabs)