docs: add BackendRegistry typing and uniform-signature rules to AI instructions

Document two new conventions in CLAUDE.md, AGENTS.md, and
.cursor/rules/project.mdc so future contributors (and AI assistants)
don't reintroduce untyped registries or per-backend dispatcher branches:

1. **Registry typing rule** -- every BackendRegistry[F] instance MUST
   be parameterised with an explicit Protocol type F defined next to
   the backends it describes.  Never declare a bare BackendRegistry
   without a type parameter (caller loses type inference on
   compute_fn).  Include a concrete example with RMSDMatrixBackendFn.

2. **Uniform signature rule** -- every backend registered in the same
   registry MUST accept the exact Protocol call signature.  If one
   backend needs an extra kwarg (e.g. periodic on mdtraj), every
   other backend MUST also accept that kwarg, silently ignoring it
   with # noqa: ARG001 and a docstring note.  This keeps the
   dispatcher branch-free and preserves type inference.

Also add an "Adding a New Backend Registry" checklist to CLAUDE.md
and AGENTS.md so contributors know the Protocol/Literal/__init__
bookkeeping needed for a brand-new multi-backend compute function.

No code changes.

Author: FridrichMethod

.cursor/rules/project.mdc

@@ -50,6 +50,27 @@ Why:
 
 **Never change a public function's default backend away from `"mdtraj"`.** Add performance notes in the docstring pointing users to `backend="numba"` or a GPU backend when they need speed.
 
+## Backend Registry Typing Rule
+
+Every `BackendRegistry[F]` instance MUST be parameterised with an explicit `Protocol` type `F` defined in the same `_backends/_<kind>.py` file. Example:
+
+```python
+from typing import Protocol
+
+class RMSDMatrixBackendFn(Protocol):
+    def __call__(
+        self,
+        traj: md.Trajectory,
+        atom_indices: NDArray[np.int_],
+    ) -> NDArray[np.float64]: ...
+
+rmsd_matrix_backends: BackendRegistry[RMSDMatrixBackendFn] = BackendRegistry(default="mdtraj")
+```
+
+**Never** declare a bare `BackendRegistry` without a type parameter -- `registry.get(backend)` would return an unbound `F`, and callers like `compute_fn = rmsd_matrix_backends.get(backend)` would lose type information. The Protocol lives next to the backends it describes (not in the shared `_registry.py`) so the registry module stays decoupled.
+
+**Uniform signature rule**: every backend registered in the same registry MUST accept the exact Protocol call signature. If one backend needs an extra keyword argument (e.g. `periodic` on mdtraj), every other backend MUST also accept that keyword, silently ignoring it if unused (`# noqa: ARG001` + docstring note). This preserves type inference at call sites and keeps dispatchers branch-free.
+
 ## Plotting Module Patterns
 
 Every `plot_*` function follows this contract:

AGENTS.md

@@ -140,17 +140,46 @@ Reasons:
 
 When reviewing or writing code, never change a public function's default backend away from `"mdtraj"`.
 
+**Uniform signature rule**: every backend registered in a given `BackendRegistry` MUST accept the exact same call signature as the Protocol type parameter on that registry. If one backend needs an extra keyword argument (e.g. `periodic` on mdtraj), every other backend in the same registry MUST also accept that keyword, silently ignoring it if unused (mark `# noqa: ARG001` and document as "accepted for Protocol uniformity, ignored"). This keeps the dispatcher free of per-backend branching and preserves type inference for callers.
+
+**Registry typing rule**: every `BackendRegistry[F]` instance MUST be parameterised with an explicit `Protocol` type `F`:
+
+```python
+from typing import Protocol
+
+class RMSDMatrixBackendFn(Protocol):
+    def __call__(
+        self,
+        traj: md.Trajectory,
+        atom_indices: NDArray[np.int_],
+    ) -> NDArray[np.float64]: ...
+
+rmsd_matrix_backends: BackendRegistry[RMSDMatrixBackendFn] = BackendRegistry(default="mdtraj")
+```
+
+Never declare a bare `BackendRegistry` without a type parameter -- `registry.get(backend)` would return an unbound `F` and the dispatcher would lose the signature of `compute_fn` at the call site. The Protocol lives in the same `_backends/_<kind>.py` file as the backends it describes (not in the shared `_registry.py`) so the registry module stays decoupled from any particular backend signature.
+
 ## Adding a New Compute Backend
 
 For existing multi-backend functions (e.g. `compute_rmsd_matrix`, pairwise distances):
 
-1. Add the implementation in the matching `src/mdpp/analysis/_backends/_<kind>.py` file, matching the existing signature.
+1. Add the implementation in the matching `src/mdpp/analysis/_backends/_<kind>.py` file, matching the `Protocol` type defined at the top of that file exactly.
 1. Use `require_torch()` / `require_jax()` / `require_cupy()` from `_backends/_imports.py` for optional GPU libraries -- never import them at module top-level.
+1. If you introduce a new keyword argument, also retrofit every existing backend in the same registry to accept it (silently ignoring when unused, marked `# noqa: ARG001`).
 1. Register in the module's `BackendRegistry` at the bottom of the file.
 1. Add the backend name to the corresponding `Literal` alias (`DistanceBackend` / `RMSDBackend`) in `_backends/_registry.py`.
-1. Add agreement tests in `tests/analysis/test_<kind>.py` guarded by the relevant `requires_*` skip marker.
+1. Add agreement tests in `tests/analysis/test_<kind>.py` guarded by the relevant `requires_*` skip marker and `@pytest.mark.gpu` (if GPU-only).
 1. **Do not change the public function's default backend** -- keep it at `"mdtraj"`.
 
+## Adding a New Backend Registry
+
+To introduce a registry for a new multi-backend compute function:
+
+1. Create `src/mdpp/analysis/_backends/_<kind>.py` with a `Protocol` class defining the shared call signature.
+1. Declare the registry as `<kind>_backends: BackendRegistry[<Kind>BackendFn] = BackendRegistry(default="mdtraj")` -- always parameterise with the Protocol so callers get typed `compute_fn` from `registry.get()`.
+1. Add a `Literal` alias to `_backends/_registry.py` (`type <Kind>Backend = Literal["mdtraj", "numba", ...]`) and re-export it from `_backends/__init__.py`.
+1. The public wrapper in `src/mdpp/analysis/<kind>.py` imports the registry and delegates via `compute_fn = <kind>_backends.get(backend)`, letting mypy infer the Protocol type at the call site.
+
 ## Adding a New Chem Function
 
 1. Create/extend a file in `src/mdpp/chem/`.

CLAUDE.md

@@ -298,18 +298,60 @@ Rationale:
 Users who want performance explicitly pass `backend="numba"` (or a GPU
 backend) and accept the PBC limitation.
 
+**Uniform signature rule**: every backend registered in a given
+`BackendRegistry` MUST accept the exact same call signature as the
+Protocol type parameter on that registry. If one backend needs an
+extra keyword argument (e.g. `periodic` on mdtraj), every other
+backend in the same registry MUST also accept that keyword, silently
+ignoring it if unused (mark `# noqa: ARG001` and document in the
+docstring that the arg is accepted for Protocol uniformity and
+ignored). This keeps the dispatcher free of per-backend branching
+and preserves type inference for callers.
+
+**Registry typing rule**: every `BackendRegistry[F]` instance MUST be
+parameterised with an explicit `Protocol` type `F`:
+
+```python
+from typing import Protocol
+
+class RMSDMatrixBackendFn(Protocol):
+    def __call__(
+        self,
+        traj: md.Trajectory,
+        atom_indices: NDArray[np.int_],
+    ) -> NDArray[np.float64]: ...
+
+rmsd_matrix_backends: BackendRegistry[RMSDMatrixBackendFn] = BackendRegistry(default="mdtraj")
+```
+
+Never declare a bare `BackendRegistry` without a type parameter --
+`registry.get(backend)` would return an unbound `F` and the dispatcher
+would lose the signature of `compute_fn` at the call site. The
+Protocol lives in the same `_backends/_<kind>.py` file as the backends
+it describes (not in the shared `_registry.py`) so the registry module
+stays decoupled from any particular backend signature.
+
 ### New compute backend
 
 To add a new backend (e.g. `cupy`) for an existing compute function like the RMSD matrix or pairwise distances:
 
 1. Add an implementation function in the matching `src/mdpp/analysis/_backends/_<kind>.py` file.
 1. Use lazy imports via `require_torch()` / `require_jax()` / `require_cupy()` from `_backends/_imports.py` -- never import optional GPU libraries at module top-level.
-1. Keep the signature aligned with existing backends in the same file (e.g. `(traj, pairs)` for distances, `(traj, atom_indices)` for RMSD matrix).
+1. Match the `Protocol` type defined at the top of the same file exactly (e.g. `RMSDMatrixBackendFn`, `DistanceBackendFn`). If you introduce a new keyword argument, also retrofit every existing backend in the same registry to accept it (silently ignoring if unused, `# noqa: ARG001`).
 1. Register the function in the module's `BackendRegistry` at the bottom of the file.
 1. Add the backend name to the corresponding `Literal` alias in `_backends/_registry.py` (`DistanceBackend` or `RMSDBackend`).
-1. Add agreement tests in `tests/analysis/test_<kind>.py` guarded by the relevant `requires_*` marker.
+1. Add agreement tests in `tests/analysis/test_<kind>.py` guarded by the relevant `requires_*` marker and `@pytest.mark.gpu` (if GPU-only).
 1. **Do not change the public function's default backend** -- keep it at `"mdtraj"`.
 
+### New backend registry
+
+To introduce a registry for a new multi-backend compute function:
+
+1. Create `src/mdpp/analysis/_backends/_<kind>.py` with a `Protocol` class defining the shared call signature.
+1. Declare the registry as `<kind>_backends: BackendRegistry[<Kind>BackendFn] = BackendRegistry(default="mdtraj")` -- always parameterise with the Protocol so callers get typed `compute_fn` from `registry.get()`.
+1. Add a `Literal` alias to `_backends/_registry.py` (`type <Kind>Backend = Literal["mdtraj", "numba", ...]`) and re-export it from `_backends/__init__.py`.
+1. The public wrapper in `src/mdpp/analysis/<kind>.py` should import the registry and delegate via `compute_fn = <kind>_backends.get(backend)`, letting mypy infer the Protocol type.
+
 ### New cheminformatics function
 
 1. Create or extend a module in `src/mdpp/chem/`.