diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..faae5f1
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,14 @@
+# CLAUDE.md
+
+Crow CI pipelines (`.crow/`) and local tooling (`local/`) that build CRAN binary packages (incl. Alpine/musl) and upload them to Backblaze B2.
+
+## Conventions
+
+- **PRs:** the remote is Forgejo on `codefloe.com`; use `fj -H codefloe.com` (not `gh`).
+- **Storage:** Backblaze B2 bucket `devxy-r-builds` (endpoints configured in the `.crow/` pipelines).
+
+## Gotchas
+
+- **B2 requires authentication for the list-bucket API.** Anonymous GET only works for individual public-read objects — an empty listing means missing credentials, not an empty bucket.
+- Weekly-rebuild pipelines run for hours; watch them as background tasks and fetch Crow logs yourself instead of having the user paste progress.
+- musl builds of packages with bundled native deps (e.g. RcppParallel/TBB) recur as failures; check for an existing patch before re-deriving a fix.