docs: add signpost llms.txt + consolidate agent instructions into AGENTS.md

.github/copilot-instructions.md

@@ -1,26 +1,10 @@
 # Copilot Coding Agent Instructions
 
-You are working on **PyAutoArray**, the low-level data structures and numerical utilities package for the PyAuto ecosystem.
-
-## Key Rules
-
-- Run tests after every change: `python -m pytest test_autoarray/`
-- Format code with `black autoarray/`
-- All files must use Unix line endings (LF, `\n`)
-- Decorated functions (`@to_array`, `@to_grid`, `@to_vector_yx`) must return **raw arrays**, not autoarray wrappers
-- The `xp` parameter controls NumPy (`xp=np`) vs JAX (`xp=jnp`) — never import JAX at module level
-- If changing public API, clearly document what changed in your PR description — downstream packages depend on this
-
-## Architecture
-
-- `autoarray/structures/` — `Array2D`, `Grid2D`, `Grid2DIrregular`, `VectorYX2D`, decorators
-- `autoarray/dataset/` — `Imaging`, `Interferometer` containers
-- `autoarray/inversion/` — Pixelization and linear inversion machinery
-- `autoarray/operators/` — `Convolver`, over-sampling utilities
-- `test_autoarray/` — Test suite
-
-## Sandboxed runs
-
-```bash
-NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python -m pytest test_autoarray/
-```
+You are working on **PyAutoArray**, the low-level data-structure and numerical
+layer of the PyAuto ecosystem (package `autoarray`).
+
+The canonical, agent-agnostic instructions for this repo live in **`AGENTS.md`** at
+the repository root — build and test commands, architecture, and the JAX / `xp` and
+grid-decorator conventions (with the deep reference in
+`docs/agents/jax_and_decorators.md`). Read it directly (Copilot does not process
+`@`-imports) and treat it as the single source of truth.

AGENTS.md

@@ -23,6 +23,14 @@ Shared utilities (e.g. `test_mode`, `jax_wrapper`) belong in autoconf.
   **autolens_workspace_test**.
 - **docs/** — Sphinx source; published to ReadTheDocs.
 
+## Architecture
+
+- `autoarray/structures/` — `Array2D`, `Grid2D`, `Grid2DIrregular`, `VectorYX2D`, and the grid decorators.
+- `autoarray/dataset/` — `Imaging` / `Interferometer` dataset containers.
+- `autoarray/inversion/` — pixelizations and linear inversion machinery.
+- `autoarray/operators/` — `Convolver`, over-sampling, and related operators.
+- `test_autoarray/` — test suite.
+
 ## Quick commands
 
 ```bash

llms.txt

@@ -0,0 +1,15 @@
+# PyAutoArray
+
+> PyAutoArray (package `autoarray`) is the foundational data-structure and numerical layer of the PyAuto ecosystem — masks, arrays, (y,x) grids, imaging/interferometer datasets, inversions/pixelizations, and the canonical home of the grid-decorator system and JAX `xp` internals that PyAutoGalaxy and PyAutoLens inherit. This file is a signpost: it points you to the right resource by intent — see where it is used, or work on the library itself.
+
+## Where it's used
+
+- PyAutoArray has no standalone workspace or tutorial series; it provides the data structures the science libraries build on. You meet it in practice through [PyAutoGalaxy](https://github.com/PyAutoLabs/PyAutoGalaxy) and [PyAutoLens](https://github.com/PyAutoLabs/PyAutoLens) (and their workspaces), which consume its arrays, grids and inversions directly.
+
+## Work on it (contributors / coding agents)
+
+- [AGENTS.md](./AGENTS.md): build, tests, architecture, and the JAX / grid-decorator conventions (deep reference in `docs/agents/jax_and_decorators.md`).
+
+## Ecosystem
+
+- Built on PyAutoConf (config); used by PyAutoGalaxy and PyAutoLens, which inherit its grid decorators and JAX `xp` backend.