diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..911139b
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,13 @@
+# CLAUDE.md
+
+CI pipelines (Crow, in `.crow/`) that build R binaries and upload them to Backblaze B2.
+
+## Conventions
+
+- **PRs:** the remote is Forgejo on `git.devxy.io`; use `fj -H git.devxy.io` (not `gh`).
+- **Storage:** Backblaze B2 bucket `devxy-r-builds` (endpoint configured in `.crow/build.yaml`).
+
+## Gotchas
+
+- **B2 requires authentication for the list-bucket API.** Anonymous GET only works for individual public-read objects — an empty bucket listing usually means missing credentials, not an empty bucket. This silently broke rebuild dedup once.
+- When a pipeline fails, fetch the Crow logs yourself instead of asking the user to paste them, and monitor reruns in the background until green.