diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..23472f6
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,25 @@
+# Agent contract
+
+The estate-wide conventions live in one place and are **not duplicated here**:
+
+**https://github.com/JorisJonkers-dev/workspace/blob/main/CLAUDE.md**
+
+Read it before doing anything non-trivial in this repository. It covers the
+things that most often go wrong, including:
+
+- **Pull request labels.** The estate uses a prefixed taxonomy — `type:`,
+  `area:`, `component:`, `priority:`, `status:`. Plain `bug` / `enhancement` /
+  `documentation` do **not** exist, and `gh pr create` fails with
+  `'bug' not found`. Run `gh label list --repo <owner>/<repo>` once before
+  passing `--label`.
+- **Verify the value, not the command.** An exit code, a `Ready` condition or
+  an accepted object is not evidence that a consumer sees what you intended.
+- Traps around workflow runs, `zsh` word-splitting, and detached submodule
+  HEADs.
+
+Duplicating that content into every repository guarantees the copies drift, so
+this file stays a pointer. Add repo-specific guidance below.
+
+---
+
+## This repository