diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..df9eec9
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,39 @@
+# AGENTS.md
+
+This file tells coding agents how to work in the HyPyP repository. It is deliberately short and contains only facts that are stable today. HyPyP is a Python library for hyperscanning analysis: it computes inter-brain connectivity and related statistics on EEG and fNIRS recordings of pairs of participants. Its results end up in scientific publications, so a silent change in a computed value is the most serious defect a contribution can introduce.
+
+## Install
+
+The project uses `uv` with a committed lock file and requires Python 3.11 or later. Install the development environment from the repository root:
+
+```bash
+uv sync --group dev
+```
+
+The accelerated backends are optional extras and are not installed by default. Add them only when the task needs them: `--extra numba`, `--extra torch`, `--extra metal` (Apple Silicon only) and `--extra cupy` (NVIDIA CUDA 12 only).
+
+## Run the tests
+
+```bash
+uv run python -m pytest tests/
+```
+
+Tests for a backend that is not installed are skipped, not failed. A green run without the extras therefore says nothing about the Numba, torch, Metal or CUDA code paths; say so when you report a result, and report the number of skipped tests along with the number that passed.
+
+## Rules for changing code
+
+When a change may alter a computed value, write an independent reference test first and see it fail, then make the fix. An independent reference is a value obtained without the code under test: a closed-form result on a synthetic signal, or a different trusted implementation. A test that only checks the shape of an output, or that compares one HyPyP backend with another, is not a reference test.
+
+Do not change a formula, a default parameter, a normalisation or a sign convention on your own judgement. These are choices of scientific method. Describe the problem, cite the literature, and leave the decision to a maintainer.
+
+Keep a pull request to one subject, and state in its description whether it changes any numerical result.
+
+## What not to touch
+
+Do not edit `uv.lock` by hand; change `pyproject.toml` and let `uv lock` regenerate it. Do not edit `docs/requirements.txt` by hand either: it is generated by `update_docs_requirements.sh`. Do not add a dependency without asking.
+
+Do not modify the sample data in `hypyp/data/` and `tests/data/`, and do not add recordings of real participants to the repository.
+
+The fNIRS code under `hypyp/fnirs/` and the Shiny dashboards under `hypyp/shiny/` have their own maintainer and an open draft pull request. Ask before changing them.
+
+Releases, tags and publication to PyPI are done by a maintainer with a dedicated procedure. Do not bump the version, create a tag or publish.
diff --git a/README.md b/README.md
index a9e0f4a..f5c8af5 100644
--- a/README.md
+++ b/README.md
@@ -49,7 +49,7 @@ For getting started with HyPyP, we have designed a little walkthrough: [getting_
 
 🌊 [wavelet/\*.py](https://github.com/ppsp-team/HyPyP/blob/master/hypyp/wavelet) — Continuous Wavelet Transform and Wavelet Transform Coherence (Patrice)
 
-📊 [shiny/\*.py](https://github.com/ppsp-team/HyPyP/blob/master/hypyp/app) — Shiny dashboards, install using `uv sync --extra shiny` (Patrice)
+📊 [shiny/\*.py](https://github.com/ppsp-team/HyPyP/blob/master/hypyp/shiny) — Shiny dashboards, install using `uv sync --extra shiny` (Patrice)
 
 ## Developer Installation (uv)