diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..2e3a59f
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,52 @@
+# Tribes Supertest
+
+`tribes-supertest` is the cross-repo live scenario test suite for Tribes OS rollout, sync, cluster, and plugin behavior.
+
+## Environment
+
+Run commands through the repo `devenv` shell:
+
+```sh
+devenv shell -- npm run typecheck
+devenv shell -- npm run scenario:single-node-plugin-rollout-rollback
+```
+
+The repo `devenv` normally provides `LEGION_UNLOCK_PASSWORD` and `LEGION_ACME_EMAIL`; do not override them unless a specific run needs it, and call that out.
+
+The `devenv` shell also exposes scenario tooling and cloud CLIs including `legion`, `hcloud`, `ovhcloud`, and `scw`. Use those tools for provider cleanup and inspection.
+
+## Scenario Runs
+
+Prefer self-signed certificate mode for supertest scenario runs by default:
+
+```sh
+SUPERTEST_CERT_MODE=self-signed devenv shell -- npm run scenario:<name>
+```
+
+Use ACME mode only when the scenario explicitly needs real certificates.
+
+Before and after live scenarios, check that provider resources are cleaned up. Use Legion state first, then provider CLIs if needed.
+
+Do not leave cloud nodes running unless the user explicitly wants live inspection.
+
+## Dev Channel Runs
+
+For rapid automatic iteration when explicitly requested, keep the `guix-tribes` dev-channel workflow isolated to the test run by setting:
+
+- `SUPERTEST_DEV_CHANNEL_MODE=1`
+- `SUPERTEST_GUIX_TRIBES_CHANNEL_BRANCH`
+- `SUPERTEST_GUIX_TRIBES_CHANNEL_COMMIT`
+- `SUPERTEST_GUIX_TRIBES_INTRO_COMMIT`
+- `SUPERTEST_GUIX_TRIBES_INTRO_FINGERPRINT`
+- `SUPERTEST_GUIX_TRIBES_SIGNER_FINGERPRINT` and `SUPERTEST_GUIX_TRIBES_SIGNER_LABEL`, when different from the intro key
+
+Do not treat a dev-channel pass as a signed `guix-tribes` `master` release baseline.
+
+## Live Debugging
+
+Common live-debug tools:
+
+- `legion ssh <node>`
+- `legion node ssh <node>`
+- `legion node rpc <node> -- <elixir-expression>`
+- provider CLIs from the `devenv` shell: `hcloud`, `ovhcloud`, `scw`